Skip to content

Commit b79b61e

Browse files
billybox1926-jpgbillybox1926-jpg
authored
Merge pull request #19 from saltines321-debug/issue-15-readme-quality-pass
Polish README structure and documentation map
2 parents 3a5b39b + e42177c commit b79b61e

1 file changed

Lines changed: 64 additions & 87 deletions

File tree

‎README.md‎

Lines changed: 64 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -6,94 +6,42 @@
66

77
A reusable, professional baseline for open source repositories.
88

9-
This template is intentionally generic so it can be adopted across teams, products, and languages with minimal changes.
10-
11-
## Why use this template
12-
13-
- **Consistent OSS standards**: ship repository health files from day one.
14-
- **Faster onboarding**: contributors and maintainers get clear guidance.
15-
- **Scalable governance**: reusable conventions for labels, milestones, and releases.
16-
- **Production-grade defaults**: practical configuration for common Git and editor workflows.
17-
- **Modular architecture**: separate core logic, integrations, extensions, config, scripts, and tests.
18-
- **Reusable DevEx**: document setup, validation, debugging, dependency, and coding standards.
19-
20-
## Included components
21-
22-
- Repository health files:
23-
- `LICENSE`
24-
- `CONTRIBUTING.md`
25-
- `SECURITY.md`
26-
- `CODE_OF_CONDUCT.md`
27-
- GitHub collaboration scaffolding:
28-
- Issue templates
29-
- Pull request template
30-
- `CODEOWNERS`
31-
- Standards and governance documentation:
32-
- `docs/REPOSITORY_STANDARDS.md`
33-
- `docs/ARCHITECTURE.md`
34-
- `docs/DEVEX.md`
35-
- `docs/examples/MODULAR_REFERENCE.md`
36-
- Modular template structure:
37-
- `core/`
38-
- `providers/`
39-
- `plugins/`
40-
- `config/`
41-
- `scripts/`
42-
- `tests/`
43-
- Baseline repository config:
44-
- `.editorconfig`
45-
- `.gitattributes`
46-
- `.gitignore`
9+
Use this template when you want clean OSS defaults, modular architecture conventions, reusable DevEx, and lightweight automation without locking a new project to one language or framework.
10+
11+
## What is included
12+
13+
- Repository health files: `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, and `CODE_OF_CONDUCT.md`
14+
- GitHub collaboration scaffolding: issue templates, pull request template, and `CODEOWNERS`
15+
- Modular project structure: `core/`, `providers/`, `plugins/`, `config/`, `scripts/`, and `tests/`
16+
- Reusable documentation for standards, architecture, DevEx, and setup
17+
- Baseline repository config: `.editorconfig`, `.gitattributes`, and `.gitignore`
18+
- Generic CI, release, bootstrap, validation, and hygiene automation
4719

4820
## Quick start
4921

5022
1. Click **Use this template** on GitHub.
5123
2. Rename the repository and update project-specific fields.
52-
3. Confirm or replace `LICENSE` for your legal requirements.
53-
4. Update contacts in `SECURITY.md`, `CODEOWNERS`, and template placeholders.
54-
5. Review `docs/DEVEX.md` and copy `config/.env.example` if runtime configuration is needed.
55-
6. Enable branch protection and required status checks.
56-
57-
## Recommended repository settings
58-
59-
- Protect the default branch (`main`/`master`).
60-
- Require pull requests and at least one approving review.
61-
- Require status checks before merge.
62-
- Enable secret scanning and dependency alerts.
63-
- Restrict force pushes and branch deletion.
64-
65-
## Versioning and releases
66-
67-
Use [Semantic Versioning](https://semver.org/) and keep a human-readable `CHANGELOG.md`.
68-
69-
- **MAJOR**: incompatible API or behavior changes.
70-
- **MINOR**: backward-compatible functionality.
71-
- **PATCH**: backward-compatible fixes.
72-
73-
## Naming conventions
74-
75-
See `docs/REPOSITORY_STANDARDS.md` for reusable naming and governance conventions.
76-
77-
## Architecture conventions
78-
79-
See `docs/ARCHITECTURE.md` for the reusable modular layout, including core/provider/plugin/config/test separation. For a concrete walkthrough, see `docs/examples/MODULAR_REFERENCE.md`.
80-
81-
## Developer experience
82-
83-
See `docs/DEVEX.md` for local workflow, environment examples, dependency standards, validation, debugging, error handling, and coding standards.
84-
85-
## Suggested next steps
86-
87-
- Review prebuilt GitHub Actions workflows in `.github/workflows/` and enable commands for your stack.
88-
- Run or adapt `bash scripts/validate.sh` for local project validation.
89-
- Add language/tool-specific linting, formatting, and tests as your project grows.
90-
- Fill in the modular folders with project-specific implementation code.
91-
- Add project-specific architecture and operations documentation in `docs/`.
92-
- Configure `release.yml` for semantic release PRs/tags if you publish artifacts.
24+
3. Review the documentation map below.
25+
4. Confirm or replace `LICENSE` for your legal requirements.
26+
5. Update contacts in `SECURITY.md`, `CODEOWNERS`, and template placeholders.
27+
6. Copy `config/.env.example` if runtime configuration is needed.
28+
7. Enable branch protection and required status checks.
29+
30+
## Documentation map
31+
32+
| Need | Start here |
33+
| --- | --- |
34+
| Local setup and CI customization | `docs/developer-setup.md` |
35+
| Developer workflow, validation, debugging, and coding standards | `docs/DEVEX.md` |
36+
| Modular architecture conventions | `docs/ARCHITECTURE.md` |
37+
| Concrete `core -> providers -> plugins` walkthrough | `docs/examples/MODULAR_REFERENCE.md` |
38+
| Branch, commit, label, milestone, and release standards | `docs/REPOSITORY_STANDARDS.md` |
39+
| Contribution expectations | `CONTRIBUTING.md` |
40+
| Security reporting | `SECURITY.md` |
9341

9442
## Repository layout
9543

96-
```
44+
```text
9745
.github/
9846
ISSUE_TEMPLATE/
9947
workflows/
@@ -108,9 +56,13 @@ docs/
10856
ARCHITECTURE.md
10957
DEVEX.md
11058
REPOSITORY_STANDARDS.md
59+
developer-setup.md
11160
examples/
11261
MODULAR_REFERENCE.md
11362
scripts/
63+
bootstrap.sh
64+
hygiene.sh
65+
validate.sh
11466
tests/
11567
CHANGELOG.md
11668
CODE_OF_CONDUCT.md
@@ -119,11 +71,36 @@ LICENSE
11971
SECURITY.md
12072
```
12173

122-
## Automation included
74+
## Automation
75+
76+
- `.github/workflows/ci.yml` runs the reusable quality workflow.
77+
- `.github/workflows/reusable-quality.yml` provides configurable hygiene, format, lint, and test checks.
78+
- `.github/workflows/release.yml` provides release automation scaffolding.
79+
- `bash scripts/bootstrap.sh` supports local setup.
80+
- `bash scripts/hygiene.sh` runs stack-agnostic repository checks.
81+
- `bash scripts/validate.sh` runs hygiene first, then project-specific checks when configured.
82+
83+
## Repository settings
84+
85+
Recommended GitHub settings:
86+
87+
- Protect the default branch (`main`/`master`).
88+
- Require pull requests and at least one approving review.
89+
- Require status checks before merge.
90+
- Enable secret scanning and dependency alerts.
91+
- Restrict force pushes and branch deletion.
92+
93+
## Versioning and releases
94+
95+
Use [Semantic Versioning](https://semver.org/) and keep a human-readable `CHANGELOG.md`.
96+
97+
- **MAJOR**: incompatible API or behavior changes.
98+
- **MINOR**: backward-compatible functionality.
99+
- **PATCH**: backward-compatible fixes.
100+
101+
## Suggested next steps
123102

124-
- Reusable quality workflow: `.github/workflows/reusable-quality.yml`
125-
- CI entry workflow: `.github/workflows/ci.yml`
126-
- Release automation workflow: `.github/workflows/release.yml`
127-
- Bootstrap script: `scripts/bootstrap.sh`
128-
- Validation script: `scripts/validate.sh`
129-
- Developer setup guide: `docs/developer-setup.md`
103+
- Enable or customize the workflow commands for your stack.
104+
- Fill the modular folders with project-specific implementation code.
105+
- Add project-specific architecture and operations notes under `docs/`.
106+
- Configure release automation if you publish artifacts.

0 commit comments

Comments
 (0)