diff --git a/docs/engineering-handbook/01-purpose.md b/docs/engineering-handbook/01-purpose.md index 88634be..3b13fa4 100644 --- a/docs/engineering-handbook/01-purpose.md +++ b/docs/engineering-handbook/01-purpose.md @@ -1,17 +1,125 @@ # Purpose -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on purpose. +The COSDS Engineering Handbook defines how contributors plan, build, review, +and maintain software for the Network Theory Applied Research Institute +(NTARI). COSDS stands for Community Orchestration Software Development Sprint: +a focused, volunteer-friendly engineering model for turning research-informed +ideas into reliable open-source systems. -## Placeholder Sections +This handbook is the shared operating manual for COSDS participants. It is +written for volunteers, maintainers, researchers, technical leads, reviewers, +and project coordinators who need a common set of expectations before they +contribute to NTARI repositories. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Handbook Goals -## Status +The handbook exists to make NTARI engineering work: -Content coming soon. +- **Understandable**: contributors can learn the workflow without private + context. +- **Reviewable**: every change has a clear purpose, owner, and audit trail. +- **Secure**: contributors avoid exposing private information, secrets, or + unsafe implementation patterns. +- **Inclusive**: volunteers can participate without already knowing NTARI's + internal practices. +- **Sustainable**: maintainers can operate repositories consistently over time. +- **Open-source aligned**: engineering choices respect AGPL-3.0 obligations and + community governance. + +## Audience + +| Audience | Primary need | Relevant chapters | +| --- | --- | --- | +| New volunteers | Understand how to participate safely and productively | [Engineering Roles](03-engineering-roles.md), [GitHub Workflow](05-github-workflow.md) | +| Maintainers | Apply consistent review, release, and repository standards | [Pull Request Process](08-pull-request-process.md), [Repository Standards](10-repository-standards.md) | +| Reviewers | Evaluate correctness, maintainability, and risk | [Code Review Standards](09-code-review-standards.md) | +| Project coordinators | Keep communication and issue flow organized | [Communication Standards](04-communication-standards.md) | +| Technical leads | Align implementation decisions with NTARI principles | [Engineering Principles](02-engineering-principles.md) | + +## Scope + +This handbook covers engineering process and repository practice for COSDS +work. It applies to NTARI-managed software, documentation, automation, and +configuration repositories unless a repository-specific guide states a stricter +requirement. + +This handbook does not replace: + +- Project-specific architecture documentation. +- Security disclosure procedures in [`../../SECURITY.md`](../../SECURITY.md). +- The repository license in [`../../LICENSE`](../../LICENSE). +- The community standards in [`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md). + +## Relationship to AGPL-3.0 + +NTARI repositories may use the GNU Affero General Public License v3.0 +(AGPL-3.0). Contributors must treat licensing as an engineering constraint, not +an afterthought. In practice, this means: + +- Do not copy incompatible code, documentation, diagrams, or configuration into + NTARI repositories. +- Preserve license notices and attribution when required. +- Keep source availability obligations in mind for network-accessible systems. +- Ask maintainers before introducing third-party dependencies, generated code, + or assets with unclear licensing. + +## How to Use This Handbook + +1. Start with [Engineering Principles](02-engineering-principles.md) to + understand the values behind the process. +2. Review [Engineering Roles](03-engineering-roles.md) to identify your role in + the sprint. +3. Follow [GitHub Workflow](05-github-workflow.md), + [Branching Strategy](06-branching-strategy.md), and + [Commit Message Standards](07-commit-message-standards.md) when preparing + changes. +4. Use [Pull Request Process](08-pull-request-process.md) and + [Code Review Standards](09-code-review-standards.md) during review. +5. Apply [Repository Standards](10-repository-standards.md) when creating or + maintaining repository structure. + +## COSDS Lifecycle + +```mermaid +flowchart LR + A[Identify work] --> B[Discuss scope] + B --> C[Create issue] + C --> D[Branch and implement] + D --> E[Open pull request] + E --> F[Review and revise] + F --> G[Merge] + G --> H[Document follow-up] +``` + +The lifecycle is intentionally simple. COSDS values small, reviewable changes +that can be understood by contributors who were not present for the original +conversation. + +## Definition of Ready + +Work is ready to begin when: + +- The problem is written down in an issue, RFC, or maintainer-approved task. +- The expected outcome is clear enough to review. +- The proposed work has an owner. +- Dependencies and risks are identified. +- The work can be completed without private or undocumented knowledge. + +## Definition of Done + +Work is done when: + +- The change is merged through the approved GitHub workflow. +- Required review has been completed. +- Tests, checks, or manual validation are documented. +- User-facing behavior or documentation has been updated where needed. +- Follow-up work is captured in issues rather than hidden in comments. + +## Related Chapters + +- [Engineering Principles](02-engineering-principles.md) +- [Communication Standards](04-communication-standards.md) +- [Pull Request Process](08-pull-request-process.md) +- [Repository Standards](10-repository-standards.md) diff --git a/docs/engineering-handbook/02-engineering-principles.md b/docs/engineering-handbook/02-engineering-principles.md index dec2c9c..7fc5165 100644 --- a/docs/engineering-handbook/02-engineering-principles.md +++ b/docs/engineering-handbook/02-engineering-principles.md @@ -1,17 +1,125 @@ # Engineering Principles -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on engineering principles. +NTARI engineering work is guided by principles that help volunteers and +maintainers make consistent decisions under uncertainty. These principles apply +across COSDS planning, implementation, review, documentation, and maintenance. -## Placeholder Sections +The principles are not slogans. They are decision tools. When a team faces a +tradeoff, the preferred choice should be the one that best preserves openness, +clarity, safety, and long-term maintainability. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Core Principles -## Status +| Principle | Meaning | Practical signal | +| --- | --- | --- | +| Open by default | Work should be understandable from the public repository whenever possible. | Decisions are linked in issues, pull requests, or documentation. | +| Small changes win | Smaller changes are easier to review, test, and revert. | Pull requests have focused scope and clear acceptance criteria. | +| Security is shared | Every contributor helps protect users, contributors, and infrastructure. | Secrets, unsafe defaults, and dependency risks are treated as blockers. | +| Documentation is engineering | Documentation is part of the delivered system. | Behavior changes include docs or a clear reason docs are not needed. | +| Review is collaboration | Review improves the work; it is not a gatekeeping performance. | Comments are specific, respectful, and tied to project outcomes. | +| Maintainability over cleverness | Future contributors must be able to understand and change the system. | Simple, explicit solutions are preferred over hidden complexity. | +| License compliance is design | AGPL-3.0 and dependency obligations influence architecture and reuse. | License impact is considered before copying or importing third-party work. | -Content coming soon. +## Decision Hierarchy + +When principles conflict, use this order: + +1. Protect people, private information, and production systems. +2. Preserve legal and license compliance. +3. Maintain correctness and user trust. +4. Keep the change reviewable and reversible. +5. Optimize for speed only after the first four conditions are met. + +## Open by Default + +COSDS work should leave a public trail that a future contributor can follow. +This does not mean everything is public. Security-sensitive information, +private reports, credentials, and protected operational details must remain +private. It does mean that non-sensitive decisions should be captured in issues, +pull requests, RFCs, or documentation. + +Good examples: + +- Linking a pull request to the issue that explains the problem. +- Summarizing a design decision in the pull request description. +- Moving a recurring review concern into documentation. + +Poor examples: + +- Relying on an unrecorded chat conversation to explain why code works. +- Merging a large change without review context. +- Adding third-party code without attribution or license notes. + +## Small Changes Win + +A small change is not defined by line count alone. A change is small when a +reviewer can understand its purpose, risk, and validation path without guessing. + +Prefer: + +- One bug fix per pull request. +- One documentation topic per pull request. +- Separate pull requests for refactoring and behavior changes. +- Follow-up issues for work discovered during review. + +Avoid: + +- Combining formatting, refactoring, and feature logic in one pull request. +- Renaming files while changing behavior unless the rename is required. +- Adding broad abstractions before a repeated pattern is proven. + +## Security Is Shared + +Security is not only the responsibility of security specialists. Every COSDS +participant must stop and ask for help when a change could expose sensitive +information, weaken access controls, or create unsafe behavior. + +Security-sensitive changes include: + +- Authentication, authorization, and session handling. +- Secrets, tokens, credentials, keys, and environment files. +- Dependency updates with known vulnerabilities. +- Deployment, networking, or infrastructure configuration. +- User data collection, storage, processing, or deletion. + +Report sensitive concerns using the repository security policy in +[`../../SECURITY.md`](../../SECURITY.md). + +## Documentation Is Engineering + +Documentation is part of how NTARI systems are designed, operated, and trusted. +A contribution is incomplete when it changes behavior but leaves future users or +maintainers unable to understand the change. + +Documentation should be: + +- Accurate enough to guide action. +- Clear enough for a new volunteer. +- Close to the system or process it describes. +- Updated in the same pull request when practical. + +See [Documentation Standards](11-documentation-standards.md) for future +repository-wide documentation practices. + +## Principle Application Example + +Scenario: a volunteer proposes a large pull request that fixes a bug, changes +formatting across many files, and introduces a new dependency. + +Recommended response: + +1. Thank the contributor and identify the useful work. +2. Ask them to split formatting from behavior changes. +3. Request dependency rationale and license review. +4. Review the bug fix independently once scope is clear. +5. Capture remaining ideas in follow-up issues. + +## Related Chapters + +- [Purpose](01-purpose.md) +- [Communication Standards](04-communication-standards.md) +- [Pull Request Process](08-pull-request-process.md) +- [Code Review Standards](09-code-review-standards.md) +- [Repository Standards](10-repository-standards.md) diff --git a/docs/engineering-handbook/03-engineering-roles.md b/docs/engineering-handbook/03-engineering-roles.md index 739ad0b..815fc4c 100644 --- a/docs/engineering-handbook/03-engineering-roles.md +++ b/docs/engineering-handbook/03-engineering-roles.md @@ -1,17 +1,149 @@ # Engineering Roles -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on engineering roles. +COSDS is designed for coordinated volunteer participation. Clear roles help +contributors understand decision rights, review expectations, and escalation +paths without requiring private organizational knowledge. -## Placeholder Sections +A person may hold more than one role. For example, a maintainer may also author +a pull request. When roles overlap, the contributor should be explicit about +which responsibility they are performing in the moment. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Role Summary -## Status +| Role | Primary responsibility | Typical GitHub activity | +| --- | --- | --- | +| Volunteer contributor | Completes scoped tasks and proposes improvements. | Issues, branches, pull requests, review responses. | +| Reviewer | Evaluates changes for correctness, clarity, risk, and maintainability. | Pull request reviews and comments. | +| Maintainer | Owns repository health, merge decisions, labels, and workflow quality. | Triage, approvals, merges, releases. | +| Technical lead | Guides technical direction and resolves engineering tradeoffs. | RFC feedback, architecture review, escalation decisions. | +| Project coordinator | Keeps sprint work organized and contributor-friendly. | Issue grooming, status updates, milestone tracking. | +| Security contact | Advises on sensitive reports and security-relevant changes. | Private reports, security reviews, remediation coordination. | -Content coming soon. +## Volunteer Contributor + +Volunteer contributors are the engine of COSDS. They may write code, +documentation, tests, configuration, examples, or review notes. + +Responsibilities: + +- Choose work from approved issues or maintainer guidance. +- Ask clarifying questions early. +- Keep changes focused and reviewable. +- Follow [GitHub Workflow](05-github-workflow.md) and + [Commit Message Standards](07-commit-message-standards.md). +- Respond respectfully to review feedback. +- Avoid adding confidential information or incompatible third-party material. + +A volunteer contributor is not expected to know everything. They are expected to +communicate clearly and keep work visible. + +## Reviewer + +Reviewers protect quality and help contributors improve their work. A reviewer +may be a maintainer, technical lead, or trusted contributor. + +Responsibilities: + +- Review the stated goal before reviewing implementation details. +- Identify blocking issues clearly. +- Distinguish required changes from suggestions. +- Check tests, documentation, accessibility, and security implications. +- Use respectful, specific feedback. + +Reviewers should follow [Code Review Standards](09-code-review-standards.md). + +## Maintainer + +Maintainers are accountable for repository health. They manage labels, +triage, branch protection, review routing, merges, and cleanup. + +Responsibilities: + +- Keep repository structure understandable. +- Ensure pull requests receive appropriate review. +- Enforce AGPL-3.0 and repository governance expectations. +- Merge only changes that meet the repository definition of done. +- Close or redirect work that is out of scope. +- Escalate unresolved technical or conduct concerns. + +Maintainers should avoid merging their own high-risk changes without independent +review. + +## Technical Lead + +Technical leads guide engineering direction. They help contributors make +architecture, implementation, and tradeoff decisions that fit NTARI goals. + +Responsibilities: + +- Clarify technical scope. +- Review significant design decisions. +- Resolve implementation tradeoffs when consensus is blocked. +- Identify when an Engineering RFC is needed. +- Coordinate with maintainers on risk and sequencing. + +Technical leads should prefer documented decisions over private direction. + +## Project Coordinator + +Project coordinators keep COSDS work navigable for volunteers. They do not need +to make technical decisions, but they help ensure work has clear ownership and +status. + +Responsibilities: + +- Help convert discussion into issues. +- Keep labels, milestones, and priorities current. +- Identify blocked work. +- Encourage updates on long-running tasks. +- Direct new volunteers to suitable first contributions. + +## Security Contact + +Security contacts help evaluate sensitive reports and security-relevant changes. +They may coordinate privately when public disclosure would increase risk. + +Responsibilities: + +- Review reports under [`../../SECURITY.md`](../../SECURITY.md). +- Advise maintainers on disclosure timing and remediation. +- Keep sensitive information out of public issues and pull requests. +- Confirm that remediation steps are documented at the appropriate level. + +## Role Interaction Flow + +```mermaid +flowchart TD + A[Contributor selects issue] --> B[Contributor opens pull request] + B --> C[Reviewer evaluates change] + C --> D{Needs technical decision?} + D -- Yes --> E[Technical lead advises] + D -- No --> F[Maintainer checks readiness] + E --> F + F --> G{Ready to merge?} + G -- Yes --> H[Maintainer merges] + G -- No --> I[Contributor revises] + I --> C +``` + +## Escalation Expectations + +Escalate when: + +- A review is blocked by unresolved technical disagreement. +- A change may create security, privacy, or license risk. +- A contributor is unsure who can approve a decision. +- A conduct concern affects collaboration. +- A pull request has stalled and needs maintainer attention. + +Use [Engineering Escalation](18-engineering-escalation.md) when that chapter is +available. Until then, ask a maintainer for the correct path. + +## Related Chapters + +- [Purpose](01-purpose.md) +- [Communication Standards](04-communication-standards.md) +- [Pull Request Process](08-pull-request-process.md) +- [Code Review Standards](09-code-review-standards.md) diff --git a/docs/engineering-handbook/04-communication-standards.md b/docs/engineering-handbook/04-communication-standards.md index f780fb9..55e59d5 100644 --- a/docs/engineering-handbook/04-communication-standards.md +++ b/docs/engineering-handbook/04-communication-standards.md @@ -1,17 +1,136 @@ # Communication Standards -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on communication standards. +COSDS depends on clear, respectful, asynchronous communication. Contributors may +be distributed across time zones, experience levels, and availability windows. +Communication should therefore preserve context, reduce ambiguity, and make it +easy for another contributor to continue the work. -## Placeholder Sections +All communication must follow the repository +[`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md). -- Overview -- Scope -- Standards -- Responsibilities -- References +## Communication Principles -## Status +| Principle | Practice | +| --- | --- | +| Default to clarity | State the problem, context, and requested action. | +| Preserve context | Link issues, pull requests, commits, and decisions. | +| Respect volunteer time | Use concise updates and avoid unnecessary urgency. | +| Be kind and direct | Focus on the work, not the person. | +| Make decisions visible | Summarize outcomes where future contributors can find them. | -Content coming soon. +## Preferred Channels + +| Need | Preferred GitHub location | Notes | +| --- | --- | --- | +| Report a defect | Bug Report issue | Include reproduction details when possible. | +| Suggest an improvement | Feature Request issue | Explain motivation and expected value. | +| Improve documentation | Documentation Improvement issue | Link the affected file or proposed location. | +| Propose a major decision | Engineering RFC issue | Include impact and open questions. | +| Review a change | Pull request review | Use comments tied to specific lines when useful. | +| Report sensitive risk | Security reporting path | Follow [`../../SECURITY.md`](../../SECURITY.md). | + +## Issue Communication + +An issue should answer three questions: + +1. What problem or opportunity are we addressing? +2. Why does it matter? +3. What outcome would be considered complete? + +Good issue comment example: + +```markdown +I can take this. I plan to update the validation logic and add a regression +test. I expect to open a pull request by Friday. If I find that the behavior is +larger than described, I will split follow-up work into a separate issue. +``` + +Poor issue comment example: + +```markdown +This is broken. Someone should fix it. +``` + +## Pull Request Communication + +Pull request descriptions should be written for reviewers who did not watch the +work happen. A useful description includes: + +- What changed. +- Why the change is needed. +- How it was validated. +- What risks or follow-ups remain. + +Review discussions should distinguish blockers from suggestions: + +- **Blocking**: must be addressed before merge. +- **Suggestion**: improves the change but is not required. +- **Question**: requests clarification before deciding. +- **Follow-up**: should become a separate issue if not handled now. + +## Status Updates + +Use status updates for long-running work. A lightweight update is enough: + +```markdown +Status update: + +- Completed: issue reproduction and failing test. +- In progress: implementation fix. +- Blocked by: maintainer decision on expected edge-case behavior. +- Next: update PR after decision. +``` + +## Decision Records + +When a decision is made in an issue or pull request, summarize it before moving +on. Future contributors should not need to infer the outcome from a long thread. + +Decision summary example: + +```markdown +Decision: we will keep this validation in the service layer for now because the +CLI and API paths share the same rule. If a third consumer appears, we will +extract the rule into a shared module. +``` + +## Meeting and Chat Summaries + +If a decision happens outside GitHub, summarize the outcome in the relevant +issue or pull request. Do not rely on private chat as the only record. + +A good summary includes: + +- Participants or roles involved. +- Decision made. +- Alternatives considered. +- Follow-up owner. +- Link to the related issue or pull request. + +## Accessibility in Communication + +Accessible communication helps all contributors participate. + +Use: + +- Descriptive links instead of "click here." +- Plain language when possible. +- Expanded acronyms on first use. +- Alt text for future images or diagrams. +- Code blocks for commands, logs, and examples. + +Avoid: + +- Screenshots of text without transcription. +- Unexplained abbreviations. +- Long unstructured comments. +- Tone that discourages questions. + +## Related Chapters + +- [Engineering Principles](02-engineering-principles.md) +- [Engineering Roles](03-engineering-roles.md) +- [GitHub Workflow](05-github-workflow.md) +- [Code Review Standards](09-code-review-standards.md) diff --git a/docs/engineering-handbook/05-github-workflow.md b/docs/engineering-handbook/05-github-workflow.md index bfb2f0b..85672b9 100644 --- a/docs/engineering-handbook/05-github-workflow.md +++ b/docs/engineering-handbook/05-github-workflow.md @@ -1,17 +1,150 @@ # GitHub Workflow -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on github workflow. +COSDS uses GitHub as the system of record for planning, implementation, review, +and maintenance. Work should be traceable from issue to branch to pull request +to merge. -## Placeholder Sections +This workflow is designed for volunteers. It favors explicit context, small +changes, and asynchronous review. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Standard Workflow -## Status +```mermaid +sequenceDiagram + participant C as Contributor + participant I as Issue + participant B as Branch + participant P as Pull Request + participant R as Reviewer + participant M as Maintainer -Content coming soon. + C->>I: Select or open scoped issue + C->>B: Create branch from default branch + C->>B: Commit focused changes + C->>P: Open pull request and link issue + R->>P: Review and request changes or approve + C->>P: Respond and revise + M->>P: Confirm readiness and merge +``` + +## Step 1: Find or Create an Issue + +Before implementing non-trivial work, confirm that the work is visible in an +issue, RFC, or maintainer-approved task. + +An issue should include: + +- Problem statement. +- Expected outcome. +- Relevant files or components. +- Acceptance criteria when known. +- Risk or dependency notes. + +Small typo fixes may go directly to a pull request if the purpose is obvious. + +## Step 2: Create a Branch + +Create a branch from the repository default branch. + +```bash +git checkout main +git pull --ff-only +git checkout -b docs/update-review-guidance +``` + +Branch names should follow [Branching Strategy](06-branching-strategy.md). + +## Step 3: Make Focused Changes + +Keep the change aligned with the issue. If you discover related work, do not +silently expand the scope. Instead: + +1. Note the discovery in the issue or pull request. +2. Ask whether it should be included. +3. Create a follow-up issue if it is separate. + +## Step 4: Commit Clearly + +Use concise, descriptive commits. Each commit should represent a coherent unit +of work. + +Good examples: + +```text +docs: add contributor onboarding checklist +test: cover invalid token handling +fix: prevent empty issue title submission +``` + +See [Commit Message Standards](07-commit-message-standards.md). + +## Step 5: Open a Pull Request + +Open a pull request when the change is ready for review or when early feedback +would reduce risk. Draft pull requests are encouraged for work in progress. + +A pull request should include: + +- Summary of the change. +- Link to the related issue or RFC. +- Validation performed. +- Risks, limitations, or follow-up work. + +See [Pull Request Process](08-pull-request-process.md). + +## Step 6: Participate in Review + +Review is collaborative. Contributors should respond to comments, ask for +clarification when needed, and push updates to the same branch. + +When responding to review: + +- Acknowledge the feedback. +- Explain the change made or the reason for a different approach. +- Mark conversations resolved only after the concern is addressed. +- Avoid force-pushing after review unless needed to clean history before merge. + +## Step 7: Merge and Follow Up + +A maintainer merges the pull request after required review and checks pass. +After merge: + +- Confirm linked issues are closed or updated. +- Create follow-up issues for deferred work. +- Remove local branches when no longer needed. + +```bash +git checkout main +git pull --ff-only +git branch -d docs/update-review-guidance +``` + +## Workflow States + +| State | Meaning | Expected action | +| --- | --- | --- | +| Open issue | Work is proposed or available. | Clarify scope and assign owner. | +| In progress | A contributor is actively working. | Provide support and avoid duplicate work. | +| Draft PR | Work is visible but not ready for final review. | Give early feedback if requested. | +| Ready for review | Author believes the change is complete. | Review for quality and risk. | +| Changes requested | Reviewer found blocking concerns. | Author revises or discusses. | +| Approved | Required reviewers accept the change. | Maintainer verifies checks and merges. | +| Merged | Change is accepted into the default branch. | Close or update related issues. | + +## Internal Link Expectations + +When adding Markdown links: + +- Prefer relative links for repository files. +- Link to related handbook chapters when context helps. +- Verify links before requesting review. +- Avoid linking to private resources from public documentation. + +## Related Chapters + +- [Branching Strategy](06-branching-strategy.md) +- [Commit Message Standards](07-commit-message-standards.md) +- [Pull Request Process](08-pull-request-process.md) +- [Code Review Standards](09-code-review-standards.md) diff --git a/docs/engineering-handbook/06-branching-strategy.md b/docs/engineering-handbook/06-branching-strategy.md index d7a3909..88e2565 100644 --- a/docs/engineering-handbook/06-branching-strategy.md +++ b/docs/engineering-handbook/06-branching-strategy.md @@ -1,17 +1,136 @@ # Branching Strategy -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on branching strategy. +COSDS uses a simple branch-based workflow. Contributors create short-lived +branches from the default branch, open pull requests, and merge only after +review and required checks. -## Placeholder Sections +The strategy favors clarity over complexity. Long-running branches and hidden +integration work make volunteer collaboration harder and should be avoided. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Default Branch -## Status +The default branch is the stable integration branch for accepted work. In most +NTARI repositories this branch is expected to be `main`. -Content coming soon. +Rules for the default branch: + +- Do not commit directly unless repository maintainers explicitly allow it for + emergency maintenance. +- Keep it releasable or publishable. +- Protect it with review and status checks when repository settings permit. +- Treat it as the source of truth for contributors. + +## Branch Naming + +Use branch names that explain the work without requiring private context. + +Recommended format: + +```text +/ +``` + +Common branch types: + +| Type | Use for | Example | +| --- | --- | --- | +| `docs` | Documentation-only changes | `docs/add-review-guidance` | +| `fix` | Bug fixes | `fix/handle-empty-config` | +| `feat` | New user-facing behavior | `feat/add-rfc-template` | +| `chore` | Maintenance and configuration | `chore/update-spellcheck` | +| `refactor` | Internal restructuring | `refactor/split-parser-module` | +| `test` | Test-only updates | `test/add-link-check-cases` | +| `security` | Security-sensitive remediation | `security/harden-token-handling` | + +## Branch Scope + +A branch should have one purpose. If a branch starts to contain unrelated work, +split it before review. + +Good branch scope: + +- Add one handbook chapter. +- Fix one broken link category. +- Update one workflow configuration. +- Implement one issue with tests. + +Poor branch scope: + +- Rewrite documentation, change CI, and refactor code together. +- Mix formatting-only changes with behavior changes. +- Add a dependency while also changing unrelated files. + +## Keeping a Branch Current + +Before opening a pull request, update your local default branch and rebase or +merge as appropriate for the repository. + +```bash +git checkout main +git pull --ff-only +git checkout docs/add-review-guidance +git rebase main +``` + +If rebasing would be confusing for shared branches, ask a maintainer before +rewriting history. + +## Force Push Guidance + +Force pushing can erase review context when used carelessly. + +Allowed: + +- Updating your own branch before review begins. +- Cleaning commit history when maintainers request it. +- Resolving rebase conflicts on a branch you own. + +Avoid: + +- Force pushing after reviewers have commented unless necessary. +- Force pushing to branches used by multiple contributors without coordination. +- Rewriting default branch history. + +When force pushing is necessary, use: + +```bash +git push --force-with-lease +``` + +`--force-with-lease` is safer than `--force` because it refuses to overwrite +remote work that you have not seen locally. + +## Branch Protection Expectations + +Maintainers should configure branch protection when the repository is ready. +Recommended protections include: + +- Require pull request review before merge. +- Require status checks for linting, tests, and link checks. +- Require branches to be up to date before merge when appropriate. +- Restrict direct pushes to the default branch. +- Include administrators unless an operational exception is documented. + +## Branch Lifecycle + +```mermaid +flowchart LR + A[Create branch] --> B[Commit focused work] + B --> C[Open pull request] + C --> D[Review and checks] + D --> E[Merge] + E --> F[Delete branch] +``` + +Delete merged branches to keep repository navigation clean. Branches with +abandoned work should be closed or archived through an issue comment explaining +why the work stopped. + +## Related Chapters + +- [GitHub Workflow](05-github-workflow.md) +- [Commit Message Standards](07-commit-message-standards.md) +- [Pull Request Process](08-pull-request-process.md) +- [Repository Standards](10-repository-standards.md) diff --git a/docs/engineering-handbook/07-commit-message-standards.md b/docs/engineering-handbook/07-commit-message-standards.md index db04756..dd21abc 100644 --- a/docs/engineering-handbook/07-commit-message-standards.md +++ b/docs/engineering-handbook/07-commit-message-standards.md @@ -1,17 +1,146 @@ # Commit Message Standards -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on commit message standards. +Commit messages are part of the engineering record. They help reviewers, +maintainers, release authors, and future contributors understand why a change +exists. -## Placeholder Sections +COSDS uses concise, structured commit messages inspired by Conventional Commits. +Repositories may adopt stricter automation later, but contributors should follow +this format now for consistency. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Format -## Status +```text +: +``` -Content coming soon. +Optional extended format: + +```text +(): + + + +