diff --git a/README.md b/README.md index baf2642..7623d18 100644 --- a/README.md +++ b/README.md @@ -6,94 +6,42 @@ A reusable, professional baseline for open source repositories. -This template is intentionally generic so it can be adopted across teams, products, and languages with minimal changes. - -## Why use this template - -- **Consistent OSS standards**: ship repository health files from day one. -- **Faster onboarding**: contributors and maintainers get clear guidance. -- **Scalable governance**: reusable conventions for labels, milestones, and releases. -- **Production-grade defaults**: practical configuration for common Git and editor workflows. -- **Modular architecture**: separate core logic, integrations, extensions, config, scripts, and tests. -- **Reusable DevEx**: document setup, validation, debugging, dependency, and coding standards. - -## Included components - -- Repository health files: - - `LICENSE` - - `CONTRIBUTING.md` - - `SECURITY.md` - - `CODE_OF_CONDUCT.md` -- GitHub collaboration scaffolding: - - Issue templates - - Pull request template - - `CODEOWNERS` -- Standards and governance documentation: - - `docs/REPOSITORY_STANDARDS.md` - - `docs/ARCHITECTURE.md` - - `docs/DEVEX.md` - - `docs/examples/MODULAR_REFERENCE.md` -- Modular template structure: - - `core/` - - `providers/` - - `plugins/` - - `config/` - - `scripts/` - - `tests/` -- Baseline repository config: - - `.editorconfig` - - `.gitattributes` - - `.gitignore` +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. + +## What is included + +- Repository health files: `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, and `CODE_OF_CONDUCT.md` +- GitHub collaboration scaffolding: issue templates, pull request template, and `CODEOWNERS` +- Modular project structure: `core/`, `providers/`, `plugins/`, `config/`, `scripts/`, and `tests/` +- Reusable documentation for standards, architecture, DevEx, and setup +- Baseline repository config: `.editorconfig`, `.gitattributes`, and `.gitignore` +- Generic CI, release, bootstrap, validation, and hygiene automation ## Quick start 1. Click **Use this template** on GitHub. 2. Rename the repository and update project-specific fields. -3. Confirm or replace `LICENSE` for your legal requirements. -4. Update contacts in `SECURITY.md`, `CODEOWNERS`, and template placeholders. -5. Review `docs/DEVEX.md` and copy `config/.env.example` if runtime configuration is needed. -6. Enable branch protection and required status checks. - -## Recommended repository settings - -- Protect the default branch (`main`/`master`). -- Require pull requests and at least one approving review. -- Require status checks before merge. -- Enable secret scanning and dependency alerts. -- Restrict force pushes and branch deletion. - -## Versioning and releases - -Use [Semantic Versioning](https://semver.org/) and keep a human-readable `CHANGELOG.md`. - -- **MAJOR**: incompatible API or behavior changes. -- **MINOR**: backward-compatible functionality. -- **PATCH**: backward-compatible fixes. - -## Naming conventions - -See `docs/REPOSITORY_STANDARDS.md` for reusable naming and governance conventions. - -## Architecture conventions - -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`. - -## Developer experience - -See `docs/DEVEX.md` for local workflow, environment examples, dependency standards, validation, debugging, error handling, and coding standards. - -## Suggested next steps - -- Review prebuilt GitHub Actions workflows in `.github/workflows/` and enable commands for your stack. -- Run or adapt `bash scripts/validate.sh` for local project validation. -- Add language/tool-specific linting, formatting, and tests as your project grows. -- Fill in the modular folders with project-specific implementation code. -- Add project-specific architecture and operations documentation in `docs/`. -- Configure `release.yml` for semantic release PRs/tags if you publish artifacts. +3. Review the documentation map below. +4. Confirm or replace `LICENSE` for your legal requirements. +5. Update contacts in `SECURITY.md`, `CODEOWNERS`, and template placeholders. +6. Copy `config/.env.example` if runtime configuration is needed. +7. Enable branch protection and required status checks. + +## Documentation map + +| Need | Start here | +| --- | --- | +| Local setup and CI customization | `docs/developer-setup.md` | +| Developer workflow, validation, debugging, and coding standards | `docs/DEVEX.md` | +| Modular architecture conventions | `docs/ARCHITECTURE.md` | +| Concrete `core -> providers -> plugins` walkthrough | `docs/examples/MODULAR_REFERENCE.md` | +| Branch, commit, label, milestone, and release standards | `docs/REPOSITORY_STANDARDS.md` | +| Contribution expectations | `CONTRIBUTING.md` | +| Security reporting | `SECURITY.md` | ## Repository layout -``` +```text .github/ ISSUE_TEMPLATE/ workflows/ @@ -108,9 +56,13 @@ docs/ ARCHITECTURE.md DEVEX.md REPOSITORY_STANDARDS.md + developer-setup.md examples/ MODULAR_REFERENCE.md scripts/ + bootstrap.sh + hygiene.sh + validate.sh tests/ CHANGELOG.md CODE_OF_CONDUCT.md @@ -119,11 +71,36 @@ LICENSE SECURITY.md ``` -## Automation included +## Automation + +- `.github/workflows/ci.yml` runs the reusable quality workflow. +- `.github/workflows/reusable-quality.yml` provides configurable hygiene, format, lint, and test checks. +- `.github/workflows/release.yml` provides release automation scaffolding. +- `bash scripts/bootstrap.sh` supports local setup. +- `bash scripts/hygiene.sh` runs stack-agnostic repository checks. +- `bash scripts/validate.sh` runs hygiene first, then project-specific checks when configured. + +## Repository settings + +Recommended GitHub settings: + +- Protect the default branch (`main`/`master`). +- Require pull requests and at least one approving review. +- Require status checks before merge. +- Enable secret scanning and dependency alerts. +- Restrict force pushes and branch deletion. + +## Versioning and releases + +Use [Semantic Versioning](https://semver.org/) and keep a human-readable `CHANGELOG.md`. + +- **MAJOR**: incompatible API or behavior changes. +- **MINOR**: backward-compatible functionality. +- **PATCH**: backward-compatible fixes. + +## Suggested next steps -- Reusable quality workflow: `.github/workflows/reusable-quality.yml` -- CI entry workflow: `.github/workflows/ci.yml` -- Release automation workflow: `.github/workflows/release.yml` -- Bootstrap script: `scripts/bootstrap.sh` -- Validation script: `scripts/validate.sh` -- Developer setup guide: `docs/developer-setup.md` +- Enable or customize the workflow commands for your stack. +- Fill the modular folders with project-specific implementation code. +- Add project-specific architecture and operations notes under `docs/`. +- Configure release automation if you publish artifacts.