Add repository setup notes

README.md

@@ -13,7 +13,7 @@ Use this template when you want clean OSS defaults, modular architecture convent
 - 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
+- Reusable documentation for standards, architecture, DevEx, setup, and repository settings
 - Baseline repository config: `.editorconfig`, `.gitattributes`, and `.gitignore`
 - Generic CI, release, bootstrap, validation, and hygiene automation
 
@@ -25,7 +25,7 @@ Use this template when you want clean OSS defaults, modular architecture convent
 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.
+7. Review `docs/REPOSITORY_SETUP.md`, then enable branch protection and required status checks.
 
 ## Documentation map
 
@@ -36,6 +36,7 @@ Use this template when you want clean OSS defaults, modular architecture convent
 | 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` |
+| GitHub repository settings, branch protection, and merge/release setup | `docs/REPOSITORY_SETUP.md` |
 | Contribution expectations | `CONTRIBUTING.md` |
 | Security reporting | `SECURITY.md` |
 
@@ -55,6 +56,7 @@ config/
 docs/
   ARCHITECTURE.md
   DEVEX.md
+  REPOSITORY_SETUP.md
   REPOSITORY_STANDARDS.md
   developer-setup.md
   examples/
@@ -82,13 +84,14 @@ SECURITY.md
 
 ## Repository settings
 
-Recommended GitHub settings:
+Recommended GitHub settings are documented in `docs/REPOSITORY_SETUP.md`.
 
-- 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.
+At minimum, review:
+
+- default branch protection
+- required status checks
+- allowed merge methods
+- release workflow expectations
 
 ## Versioning and releases
 

docs/REPOSITORY_SETUP.md

@@ -0,0 +1,78 @@
+# Repository Setup Notes
+
+Some template quality depends on GitHub repository settings rather than committed files. Review these settings after creating a new repository from this template.
+
+Keep this guidance generic. Project-specific rules can be stricter when needed.
+
+## Default branch
+
+Recommended default branch: `main`.
+
+After the first stable setup pass, protect the default branch so all important changes flow through pull requests.
+
+## Branch protection
+
+Recommended default branch protection:
+
+- require pull requests before merging
+- require at least one approval before merging
+- require status checks before merging
+- require branches to be up to date before merging when practical
+- block force pushes on protected branches
+- block branch deletion on protected branches
+
+For small solo projects, keep the rules lightweight enough that maintenance does not become painful. For shared projects, prefer stricter review and status-check rules.
+
+## Required status checks
+
+At minimum, require the main CI workflow once it is stable for the project.
+
+Suggested required checks:
+
+- repository hygiene
+- format check, when configured
+- lint, when configured
+- tests, when configured
+
+The template starts with generic hygiene checks. Downstream projects should enable stack-specific checks as soon as they choose a runtime or framework.
+
+## Merge methods
+
+Recommended defaults:
+
+- **Squash merge** for small feature, docs, cleanup, and chore PRs
+- **Merge commit** for larger work where preserving branch history helps review
+- **Rebase merge** only when the team is comfortable with linear history and the PR does not need merge context
+
+Keep allowed merge methods simple. If maintainers are unsure, allow squash and merge commits, then document the project preference in `CONTRIBUTING.md`.
+
+## Auto-merge
+
+Auto-merge is useful when:
+
+- branch protection is configured
+- required checks are reliable
+- dependency or maintenance PRs are low risk
+- the repository has clear review rules
+
+Avoid auto-merge while the project is still defining its first CI checks or release process.
+
+## Release workflow expectations
+
+The release workflow is scaffolding. Before relying on it:
+
+1. Confirm the project uses Semantic Versioning.
+2. Confirm `CHANGELOG.md` expectations.
+3. Decide whether releases are tag-only, notes-only, or artifact-producing.
+4. Test the workflow manually before making it required.
+5. Document any package publishing steps in project-specific docs.
+
+## Practical setup order
+
+1. Create the repository from the template.
+2. Update project identity, contacts, and ownership files.
+3. Configure CI commands for the project stack.
+4. Confirm the hygiene workflow passes.
+5. Enable branch protection and required checks.
+6. Decide the default merge method.
+7. Configure release automation when the project is ready to publish.