diff --git a/docs/engineering-handbook/18-engineering-escalation.md b/docs/engineering-handbook/18-engineering-escalation.md index 5351a66..f581947 100644 --- a/docs/engineering-handbook/18-engineering-escalation.md +++ b/docs/engineering-handbook/18-engineering-escalation.md @@ -1,17 +1,144 @@ # Engineering Escalation -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on engineering escalation. +Engineering escalation is the process COSDS contributors use when normal issue, +pull request, or review discussion cannot resolve a risk, decision, or blocker. +Escalation is not a failure. It is a governance tool that protects contributor +time, repository quality, security, licensing, and NTARI's open-source mission. -## Placeholder Sections +Escalation should be visible when the topic is safe for public discussion and +private when the topic involves security, privacy, conduct, or sensitive +operational details. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Escalation Principles -## Status +| Principle | Practice | +| --- | --- | +| Escalate early | Raise blockers before work stalls or contributors duplicate effort. | +| Use the right channel | Public issues for routine blockers; private paths for sensitive concerns. | +| Preserve context | Link issues, pull requests, logs, decisions, and attempted resolutions. | +| Seek accountable decisions | Identify who can decide, not only who can discuss. | +| Document outcomes | Summarize decisions where future contributors can find them. | -Content coming soon. +## When to Escalate + +Escalate when: + +- A pull request is blocked by unresolved technical disagreement. +- A change may introduce security, privacy, licensing, or compliance risk. +- Review comments conflict and the author needs a decision. +- An issue is blocked by missing scope, ownership, or acceptance criteria. +- A workflow, release, or repository setting affects contributor safety. +- Conduct concerns affect collaboration. +- A decision has impact beyond one repository. + +Do not escalate routine questions before attempting normal clarification through +[Communication Standards](04-communication-standards.md). + +## Escalation Levels + +| Level | Use for | Decision owner | +| --- | --- | --- | +| Contributor clarification | Missing context or simple scope question. | Issue owner or reviewer | +| Maintainer decision | Repository workflow, merge, label, or ownership decision. | Repository maintainer | +| Technical lead decision | Architecture, implementation, or risk tradeoff. | Technical lead | +| Security escalation | Sensitive vulnerability, secret, or abuse concern. | Security contact or maintainer | +| Governance escalation | Cross-repository policy, licensing, or conduct matter. | NTARI governance owner | + +## Standard Escalation Flow + +```mermaid +flowchart TD + A[Contributor or reviewer identifies blocker] --> B{Sensitive issue?} + B -- Yes --> C[Use private security or conduct path] + B -- No --> D[Summarize blocker in issue or PR] + D --> E{Repository maintainer can decide?} + E -- Yes --> F[Maintainer decides or assigns owner] + E -- No --> G[Escalate to technical lead] + G --> H{Cross-repository or policy impact?} + H -- Yes --> I[Escalate to NTARI governance] + H -- No --> J[Technical lead decides] + C --> K[Remediate safely] + F --> L[Document decision] + I --> L + J --> L + K --> L +``` + +## Escalation Request Format + +Use this format in an issue or pull request when public discussion is safe: + +```markdown +## Escalation Request + +### Decision needed +What specific decision is required? + +### Context +Link issues, pull requests, commits, logs, or prior discussion. + +### Options considered +1. Option A: benefits and risks. +2. Option B: benefits and risks. + +### Recommendation +State the preferred option and why. + +### Deadline or impact +Explain whether work is blocked and by when a decision is needed. +``` + +## Sensitive Escalations + +Use private reporting paths for: + +- Suspected vulnerabilities. +- Secret exposure. +- Personal data exposure. +- Harassment, threats, or retaliation. +- Private infrastructure details. +- Unapproved disclosure of sensitive operational information. + +Follow [`../../SECURITY.md`](../../SECURITY.md) for security and repository +integrity issues. Follow [`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md) +for conduct concerns. + +## Decision Documentation + +After an escalation is resolved, document: + +- The decision. +- The decision owner. +- The reason for the decision. +- Follow-up issues or pull requests. +- Any constraints or expiration date. + +Do not publish sensitive details. When the full decision cannot be public, +record a public-safe summary such as: + +```markdown +Decision: maintainers accepted the remediation approach discussed through the +private security process. Public documentation will be updated after the fix is +released. +``` + +## Escalation Checklist + +Before escalating, confirm: + +- The blocker is clearly stated. +- Existing handbook guidance has been checked. +- Relevant issue or pull request links are included. +- The requested decision is specific. +- Sensitive information is not posted publicly. +- The right owner or role is requested. + +## Related Chapters + +- [Engineering Roles](03-engineering-roles.md) +- [Communication Standards](04-communication-standards.md) +- [Security Standards](13-security-standards.md) +- [Professional Conduct](17-professional-conduct.md) +- [GitHub Governance](26-github-governance.md) diff --git a/docs/engineering-handbook/19-release-management.md b/docs/engineering-handbook/19-release-management.md index eece20c..bd88416 100644 --- a/docs/engineering-handbook/19-release-management.md +++ b/docs/engineering-handbook/19-release-management.md @@ -1,17 +1,151 @@ # Release Management -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on release management. +Release management is the governance process for deciding when a change becomes +available to users, contributors, or downstream operators. In COSDS, releases +must be traceable, reviewable, license-aware, and reversible when practical. -## Placeholder Sections +A release may be a software package, documentation publication, container image, +configuration bundle, or tagged repository state. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Release Principles -## Status +| Principle | Practice | +| --- | --- | +| Release from reviewed work | Only release changes merged through the approved workflow. | +| Keep provenance clear | Use tags, release notes, and linked pull requests. | +| Prefer repeatability | Document commands and automate safely. | +| Protect users | Include validation, rollback notes, and known limitations. | +| Respect AGPL-3.0 | Preserve source availability, license notices, and attribution. | +| Separate release from deployment | Publishing an artifact is not always the same as deploying it. | -Content coming soon. +## Release Types + +| Type | Use for | Example | +| --- | --- | --- | +| Documentation release | Publishing updated docs or handbook content. | Developer Portal publication | +| Patch release | Backward-compatible fix. | Security or bug fix | +| Minor release | Backward-compatible feature or improvement. | New CLI command | +| Major release | Breaking change or migration requirement. | Schema change | +| Emergency release | Time-sensitive remediation. | Secret exposure fix | + +## Release Lifecycle + +```mermaid +flowchart LR + A[Plan scope] --> B[Merge reviewed changes] + B --> C[Run release checks] + C --> D[Prepare release notes] + D --> E[Tag release] + E --> F[Publish artifact or documentation] + F --> G[Monitor and capture follow-up] +``` + +## Release Readiness Criteria + +A release is ready when: + +- Included changes are merged into the release branch or default branch. +- Required checks pass or exceptions are documented. +- Release notes summarize user-visible changes. +- Breaking changes and migration steps are documented. +- License and attribution obligations are satisfied. +- Security-sensitive timing has been coordinated. +- Rollback or remediation steps are understood. + +## Versioning Guidance + +Repositories should define their versioning approach before the first public +release. Semantic Versioning is appropriate for many software projects, but +some documentation repositories may use date-based releases or named milestones. + +| Versioning model | Best for | Example | +| --- | --- | --- | +| Semantic Versioning | Libraries, APIs, CLIs, services with compatibility promises. | `v1.4.2` | +| Calendar Versioning | Documentation snapshots or scheduled releases. | `2026.08` | +| Milestone labels | Early-stage repositories without stable release promises. | `cosds-alpha` | + +## Release Notes + +Release notes should include: + +- Summary of the release. +- Notable changes. +- Breaking changes or migrations. +- Security notes that are safe to publish. +- Contributors or acknowledgements when appropriate. +- Links to related issues, pull requests, and tags. + +Example: + +```markdown +## v1.2.0 + +### Added + +- Added Engineering RFC issue form. + +### Changed + +- Updated pull request checklist for documentation validation. + +### Security + +- No security-sensitive changes in this release. +``` + +## Emergency Releases + +Emergency releases are allowed when delaying would create unacceptable risk. +They still require traceability. + +Minimum emergency release steps: + +1. Notify maintainers and security contacts. +2. Create the smallest safe remediation. +3. Obtain appropriate review for the risk level. +4. Release from a known commit. +5. Document public-safe notes. +6. Create follow-up issues for cleanup and retrospective review. + +## Documentation Publication + +When documentation is published through a future site generator such as +Docusaurus, the publication process should: + +- Build from reviewed Markdown. +- Run link and spelling checks before publication. +- Preserve source repository links. +- Avoid publishing drafts or sensitive notes. +- Record the published revision. + +Do not add publication tooling until NTARI approves the publishing architecture. + +## Release Checklist + +Before release: + +- Confirm scope and release owner. +- Confirm required pull requests are merged. +- Run required checks. +- Review license and attribution impact. +- Draft release notes. +- Confirm rollback or remediation path. +- Tag or identify the release commit. + +After release: + +- Verify publication or artifact availability. +- Update related issues and milestones. +- Monitor reports. +- Create follow-up issues. +- Record lessons learned when needed. + +## Related Chapters + +- [CI/CD Standards](12-ci-cd-standards.md) +- [Security Standards](13-security-standards.md) +- [Pull Request Process](08-pull-request-process.md) +- [Repository Standards](10-repository-standards.md) +- [Continuous Improvement](21-continuous-improvement.md) diff --git a/docs/engineering-handbook/20-engineering-metrics.md b/docs/engineering-handbook/20-engineering-metrics.md index 6e61741..d216f35 100644 --- a/docs/engineering-handbook/20-engineering-metrics.md +++ b/docs/engineering-handbook/20-engineering-metrics.md @@ -1,17 +1,123 @@ # Engineering Metrics -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on engineering metrics. +Engineering metrics help NTARI understand whether COSDS work is healthy, +reviewable, inclusive, and sustainable. Metrics should guide improvement, not +punish contributors. Volunteer communities require careful interpretation +because availability varies. -## Placeholder Sections +Metrics must be used with context. A number without context can mislead. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Metrics Principles -## Status +| Principle | Practice | +| --- | --- | +| Measure systems, not worth | Use metrics to improve process, not judge individual value. | +| Prefer trends | Compare changes over time instead of reacting to one data point. | +| Include qualitative context | Pair numbers with contributor feedback and retrospectives. | +| Protect privacy | Do not publish sensitive personal or operational data. | +| Keep metrics actionable | Track measures that can lead to process improvements. | -Content coming soon. +## Core KPIs + +| KPI | What it measures | Why it matters | +| --- | --- | --- | +| Issue triage time | Time from issue creation to first maintainer response. | Shows whether contributors receive timely direction. | +| Pull request review time | Time from review request to first substantive review. | Helps maintain volunteer momentum. | +| Pull request cycle time | Time from PR open to merge or close. | Indicates review and delivery flow. | +| Change failure rate | Share of merged changes that require rollback or urgent fix. | Highlights quality and risk management. | +| CI pass rate | Share of PRs with passing required checks. | Shows automation reliability and contributor readiness. | +| Documentation freshness | Pages reviewed or updated within an agreed period. | Reduces stale guidance. | +| Contributor activation | New contributors who complete a first accepted contribution. | Measures onboarding effectiveness. | +| Escalation resolution time | Time from escalation request to documented decision. | Shows governance responsiveness. | + +## Supporting Metrics + +Additional metrics may include: + +- Number of open issues by label. +- Number of blocked issues. +- Ratio of draft to ready pull requests. +- Frequency of stale issue cleanup. +- Number of broken links detected. +- Number of documentation pages with owners. +- Percentage of repositories with required community health files. + +## Metrics Flow + +```mermaid +flowchart LR + A[Collect signals] --> B[Review trends] + B --> C[Identify bottleneck] + C --> D[Choose improvement] + D --> E[Implement change] + E --> F[Measure impact] + F --> B +``` + +## Interpretation Guidance + +Metrics should be reviewed with context. + +Example interpretations: + +| Observation | Possible meaning | Follow-up question | +| --- | --- | --- | +| PR review time increases | Maintainers are overloaded or PRs are too large. | Are reviews waiting on owners or scope clarity? | +| CI pass rate decreases | Checks are flaky or contributors lack setup guidance. | Are failures actionable and documented? | +| Issue count increases | Community engagement is growing or triage is delayed. | How many issues are actionable? | +| Contributor activation drops | Onboarding is unclear or first issues are too hard. | Do volunteers have good first issues? | + +## Anti-Patterns + +Avoid: + +- Ranking volunteers by number of commits. +- Treating review speed as more important than review quality. +- Ignoring security or accessibility because they are harder to quantify. +- Using metrics without explaining limitations. +- Publishing personal performance data without consent and governance approval. + +## Data Sources + +Potential sources include: + +- GitHub issues and pull requests. +- GitHub Actions results. +- Release notes. +- Repository readiness reviews. +- Contributor surveys. +- Retrospective notes. + +Data collection should respect privacy and platform terms. + +## KPI Review Checklist + +When reviewing metrics, ask: + +- What decision will this metric inform? +- Is the data complete enough to trust? +- What context explains the trend? +- Could this metric create harmful incentives? +- What improvement will we try next? +- How will we know whether the improvement worked? + +## Reporting Cadence + +Recommended cadence: + +| Cadence | Review focus | +| --- | --- | +| Weekly during sprint | Blockers, review queues, CI failures, urgent issues. | +| Monthly | Trends, contributor onboarding, documentation freshness. | +| Per release | Quality, release readiness, follow-up work. | +| Quarterly | Governance, tooling, repository standards, strategic improvements. | + +## Related Chapters + +- [Issue Management](14-issue-management.md) +- [Pull Request Process](08-pull-request-process.md) +- [Code Review Standards](09-code-review-standards.md) +- [Continuous Improvement](21-continuous-improvement.md) +- [Volunteer Expectations](16-volunteer-expectations.md) diff --git a/docs/engineering-handbook/21-continuous-improvement.md b/docs/engineering-handbook/21-continuous-improvement.md index 1ee01ff..f4541a4 100644 --- a/docs/engineering-handbook/21-continuous-improvement.md +++ b/docs/engineering-handbook/21-continuous-improvement.md @@ -1,17 +1,153 @@ # Continuous Improvement -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on continuous improvement. +Continuous improvement is the COSDS practice of learning from work and making +the next sprint safer, clearer, and more effective. It turns review comments, +metrics, incidents, contributor feedback, and release outcomes into actionable +changes. -## Placeholder Sections +Improvement work should be visible, prioritized, and reviewed like any other +engineering work. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Improvement Principles -## Status +| Principle | Practice | +| --- | --- | +| Improve the system | Fix process gaps, not only individual symptoms. | +| Keep changes small | Test process improvements in manageable increments. | +| Use evidence | Combine metrics, examples, and contributor feedback. | +| Document decisions | Capture what changed and why. | +| Close the loop | Verify whether the improvement helped. | -Content coming soon. +## Improvement Sources + +Continuous improvement inputs include: + +- Retrospectives. +- Pull request review patterns. +- CI failures. +- Security findings. +- Release follow-up issues. +- Contributor onboarding feedback. +- Documentation gaps. +- Engineering metrics. + +See [Engineering Metrics](20-engineering-metrics.md) for KPI guidance. + +## Improvement Process + +```mermaid +flowchart TD + A[Observe issue or opportunity] --> B[Capture evidence] + B --> C[Create improvement issue] + C --> D[Prioritize with maintainers] + D --> E[Implement focused change] + E --> F[Review impact] + F --> G{Improved?} + G -- Yes --> H[Document standard] + G -- No --> I[Adjust or revert] + I --> C +``` + +## Retrospectives + +Retrospectives should be lightweight and blameless. The goal is to improve the +system of work. + +Recommended prompts: + +- What helped contributors make progress? +- What blocked or slowed work? +- What confused new contributors? +- Which review comments repeated across pull requests? +- Which checks failed most often? +- What should we start, stop, or continue? + +## Improvement Issue Template + +Use this structure when proposing process improvement: + +```markdown +## Improvement Opportunity + +Describe the process gap or recurring problem. + +## Evidence + +Link examples, metrics, issues, pull requests, or feedback. + +## Proposed Change + +Describe the smallest useful improvement. + +## Expected Outcome + +Explain how contributors or maintainers will benefit. + +## Validation + +Describe how we will know whether the change helped. +``` + +## Prioritization + +Prioritize improvements that: + +- Reduce security or licensing risk. +- Unblock multiple contributors. +- Reduce repeated maintainer work. +- Improve onboarding. +- Make CI failures more actionable. +- Prevent release or operational mistakes. + +Defer improvements that are speculative, too broad, or not tied to observed +friction. + +## Change Management + +Process changes should be introduced carefully. + +Checklist: + +- Identify affected contributors. +- Update relevant handbook chapters. +- Update templates or workflows when needed. +- Announce the change in the relevant issue or pull request. +- Provide examples. +- Review impact after a defined period. + +## Learning from Incidents + +An incident may involve security, release failure, workflow breakage, or +community harm. Incident learning should be blameless and action-oriented. + +Public-safe incident follow-up should include: + +- What happened. +- What impact occurred. +- What was fixed. +- What process improvement will prevent recurrence. +- What details cannot be public and why. + +Sensitive details must follow [`../../SECURITY.md`](../../SECURITY.md) and +[`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md) as applicable. + +## Improvement Backlog Checklist + +Maintainers should periodically review whether: + +- Improvement issues have clear owners. +- High-risk process gaps are prioritized. +- Completed improvements were documented. +- Repeated review comments have become guidance. +- Metrics show whether changes helped. +- Stale improvement proposals should be closed or reframed. + +## Related Chapters + +- [Engineering Metrics](20-engineering-metrics.md) +- [Issue Management](14-issue-management.md) +- [Release Management](19-release-management.md) +- [Documentation Standards](11-documentation-standards.md) +- [Engineering Escalation](18-engineering-escalation.md) diff --git a/docs/engineering-handbook/22-repository-checklist.md b/docs/engineering-handbook/22-repository-checklist.md index 847a8d1..d4dd2f9 100644 --- a/docs/engineering-handbook/22-repository-checklist.md +++ b/docs/engineering-handbook/22-repository-checklist.md @@ -1,17 +1,129 @@ # Repository Checklist -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on repository checklist. +The repository checklist helps maintainers evaluate whether an NTARI repository +is ready for COSDS participation. It covers governance, GitHub compatibility, +security, documentation, automation, accessibility, licensing, and release +readiness. -## Placeholder Sections +Use this checklist during repository creation, readiness reviews, and periodic +maintenance. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Compliance Summary -## Status +| Area | Required outcome | +| --- | --- | +| Governance | Maintainers, ownership, and contribution rules are visible. | +| Licensing | License and third-party obligations are clear. | +| Security | Sensitive reporting and secret handling are defined. | +| GitHub workflow | Issues, pull requests, reviews, and branch protections are usable. | +| Documentation | README and contributor guidance are accurate. | +| Automation | CI checks match repository risk and are actionable. | +| Accessibility | Public documentation is readable and inclusive. | +| Cleanliness | Generated, local, and sensitive files are not tracked. | -Content coming soon. +## Required Files Checklist + +- [ ] `README.md` explains repository purpose and current status. +- [ ] `LICENSE` is present and appropriate for the repository. +- [ ] `CONTRIBUTING.md` explains how to contribute. +- [ ] `CODE_OF_CONDUCT.md` defines community standards. +- [ ] `SECURITY.md` explains sensitive reporting expectations. +- [ ] `CODEOWNERS` routes review responsibility. +- [ ] `.gitignore` excludes local, generated, and sensitive files. +- [ ] `.editorconfig` defines basic formatting rules. + +See [Repository Standards](10-repository-standards.md). + +## GitHub Configuration Checklist + +- [ ] Pull request template is present. +- [ ] Issue templates support bugs, documentation, feature requests, and RFCs. +- [ ] Labels match issue templates and triage needs. +- [ ] Default branch is protected when appropriate. +- [ ] Required reviews are configured for protected branches. +- [ ] Required status checks are stable before enforcement. +- [ ] CODEOWNERS teams exist and have repository access. +- [ ] Workflow permissions use least privilege. + +## Documentation Checklist + +- [ ] README uses clear, accessible language. +- [ ] Internal links resolve. +- [ ] Public documentation avoids private links. +- [ ] Examples are safe to copy. +- [ ] Images or diagrams include text explanations. +- [ ] Project-specific docs link to handbook standards instead of duplicating + shared policy. +- [ ] Placeholder text is not present in production pages. + +See [Documentation Standards](11-documentation-standards.md). + +## Security Checklist + +- [ ] No secrets, credentials, or private keys are committed. +- [ ] `.env` files are ignored unless they are safe examples. +- [ ] Security reporting path is documented. +- [ ] Dependency additions are reviewed for license and security impact. +- [ ] Workflows do not expose secrets to untrusted code. +- [ ] Logs and examples avoid sensitive values. +- [ ] Security-sensitive procedures are not overexposed publicly. + +See [Security Standards](13-security-standards.md). + +## CI/CD Checklist + +- [ ] Markdown linting runs for documentation changes when appropriate. +- [ ] Link checking runs for Markdown changes or on a schedule. +- [ ] Spellcheck is available for contributor-facing documentation. +- [ ] Tests run for code changes. +- [ ] Workflow failures are actionable. +- [ ] Third-party actions are approved by maintainers. +- [ ] Release and deployment workflows are separate from validation workflows. + +See [CI/CD Standards](12-ci-cd-standards.md). + +## Release Readiness Checklist + +- [ ] Release owner is identified. +- [ ] Release scope is documented. +- [ ] Required changes are merged. +- [ ] Release notes are drafted. +- [ ] License and attribution requirements are reviewed. +- [ ] Rollback or remediation plan is known. +- [ ] Published artifact or documentation can be verified. + +See [Release Management](19-release-management.md). + +## Repository Readiness Flow + +```mermaid +flowchart TD + A[Start readiness review] --> B[Check required files] + B --> C[Check GitHub configuration] + C --> D[Check documentation] + D --> E[Check security] + E --> F[Check CI/CD] + F --> G{Release-ready?} + G -- Yes --> H[Approve repository for COSDS work] + G -- No --> I[Create improvement issues] + I --> B +``` + +## Review Cadence + +| Cadence | Focus | +| --- | --- | +| New repository | Required files, license, security, contribution path. | +| Before sprint | Issues, labels, onboarding, CI health. | +| Before release | Release notes, checks, license, rollback. | +| Quarterly | Ownership, workflow health, documentation freshness. | + +## Related Chapters + +- [Repository Standards](10-repository-standards.md) +- [Documentation Standards](11-documentation-standards.md) +- [Security Standards](13-security-standards.md) +- [CI/CD Standards](12-ci-cd-standards.md) +- [Release Management](19-release-management.md) diff --git a/docs/engineering-handbook/23-volunteer-onboarding-checklist.md b/docs/engineering-handbook/23-volunteer-onboarding-checklist.md index 82484a2..4c52850 100644 --- a/docs/engineering-handbook/23-volunteer-onboarding-checklist.md +++ b/docs/engineering-handbook/23-volunteer-onboarding-checklist.md @@ -1,17 +1,147 @@ # Volunteer Onboarding Checklist -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on volunteer onboarding checklist. +The volunteer onboarding checklist helps new COSDS participants move from +interest to a safe, reviewable first contribution. It also helps maintainers and +project coordinators provide consistent support without relying on private +context. -## Placeholder Sections +Use this checklist for self-service onboarding, sprint preparation, and mentor +support. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Onboarding Goals -## Status +A new volunteer should be able to: -Content coming soon. +- Understand NTARI's contribution expectations. +- Choose appropriate work. +- Communicate status and blockers. +- Open a focused pull request. +- Respond to review professionally. +- Avoid common security, licensing, and documentation mistakes. + +## Volunteer Readiness Checklist + +Before starting work: + +- [ ] Read the repository `README.md`. +- [ ] Read [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md). +- [ ] Read [`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md). +- [ ] Review [Purpose](01-purpose.md). +- [ ] Review [Engineering Principles](02-engineering-principles.md). +- [ ] Review [Volunteer Expectations](16-volunteer-expectations.md). +- [ ] Confirm you can use GitHub issues and pull requests. +- [ ] Confirm you understand how to report sensitive issues through + [`../../SECURITY.md`](../../SECURITY.md). + +## First Issue Checklist + +Before claiming an issue: + +- [ ] The issue is still open. +- [ ] The issue has enough detail to begin. +- [ ] The work is suitable for your experience and availability. +- [ ] The issue is not security-sensitive unless a maintainer directed you to it. +- [ ] You have asked clarifying questions if scope is unclear. +- [ ] You have commented with your intent to work on it. + +Good claim comment: + +```markdown +I would like to work on this. I plan to update the documentation example and +verify the related links. I will open a draft pull request if I need early +feedback. +``` + +## Local Setup Checklist + +Before editing: + +- [ ] Fork or clone the repository as directed. +- [ ] Create a branch from the default branch. +- [ ] Read any project-specific setup instructions. +- [ ] Avoid adding real secrets or private configuration. +- [ ] Confirm local tools are available if the project requires them. + +Branch example: + +```bash +git checkout main +git pull --ff-only +git checkout -b docs/clarify-validation-example +``` + +See [Branching Strategy](06-branching-strategy.md). + +## Pull Request Checklist + +Before requesting review: + +- [ ] The pull request has a clear title. +- [ ] The description explains what changed and why. +- [ ] The related issue is linked. +- [ ] Validation steps are listed. +- [ ] The change is focused. +- [ ] Internal links are valid if Markdown changed. +- [ ] No placeholder text remains in production documentation. +- [ ] No secrets or private information are included. +- [ ] Licensing or attribution questions are raised in the PR. + +See [Pull Request Process](08-pull-request-process.md). + +## Review Response Checklist + +During review: + +- [ ] Read all comments before responding. +- [ ] Ask for clarification when needed. +- [ ] Address blocking comments before requesting another review. +- [ ] Explain any alternative approach respectfully. +- [ ] Keep new work scoped to the pull request goal. +- [ ] Create follow-up issues for separate work. + +See [Code Review Standards](09-code-review-standards.md). + +## Onboarding Flow + +```mermaid +flowchart TD + A[Read governance files] --> B[Review handbook basics] + B --> C[Choose appropriate issue] + C --> D[Comment with intent] + D --> E[Create branch] + E --> F[Open pull request] + F --> G[Respond to review] + G --> H[First contribution merged] +``` + +## Maintainer Support Checklist + +Maintainers and coordinators should provide: + +- [ ] Clear first issues. +- [ ] Prompt acknowledgment of volunteer intent. +- [ ] Scope clarification when needed. +- [ ] Respectful review feedback. +- [ ] Guidance on validation commands. +- [ ] Follow-up issues when work expands. +- [ ] Recognition of accepted contributions. + +## Common Onboarding Pitfalls + +| Pitfall | Prevention | +| --- | --- | +| Starting without issue context | Ask contributors to comment before beginning. | +| Pull request is too large | Encourage smaller scoped changes. | +| Contributor lacks validation steps | Provide examples in the PR template. | +| Review feels personal | Use conduct and review standards. | +| Security detail is posted publicly | Redirect to private reporting path. | + +## Related Chapters + +- [Volunteer Expectations](16-volunteer-expectations.md) +- [Professional Conduct](17-professional-conduct.md) +- [GitHub Workflow](05-github-workflow.md) +- [Issue Management](14-issue-management.md) +- [Pull Request Process](08-pull-request-process.md) diff --git a/docs/engineering-handbook/24-revision-history.md b/docs/engineering-handbook/24-revision-history.md index 05a4fda..01e24a2 100644 --- a/docs/engineering-handbook/24-revision-history.md +++ b/docs/engineering-handbook/24-revision-history.md @@ -1,17 +1,129 @@ # Revision History -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on revision history. +Revision history records how the COSDS Engineering Handbook changes over time. +It helps contributors understand when standards changed, why they changed, and +where to find the related pull requests or decisions. -## Placeholder Sections +This chapter defines the governance process for handbook revisions. The detailed +history table should be updated as handbook content changes. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Revision Governance -## Status +Handbook revisions must be: -Content coming soon. +- Proposed through issues, pull requests, or RFCs when appropriate. +- Reviewed by maintainers or owners for the affected topic. +- Linked to related decisions, metrics, incidents, or retrospectives. +- Written in production-ready Markdown. +- Compatible with AGPL-3.0 governance and open-source contribution practices. + +## When to Update the Handbook + +Update the handbook when: + +- A workflow changes. +- Governance expectations change. +- Repeated review comments reveal missing guidance. +- A release or incident creates a new standard. +- A repository checklist requirement changes. +- Volunteer onboarding feedback identifies confusion. +- A Docusaurus publication decision changes authoring requirements. + +## Revision Types + +| Type | Description | Review expectation | +| --- | --- | --- | +| Editorial | Clarifies wording without changing expectations. | Standard documentation review. | +| Process | Changes how contributors or maintainers work. | Maintainer review required. | +| Governance | Changes ownership, escalation, security, or licensing expectations. | Governance owner review required. | +| Security | Changes security guidance or disclosure handling. | Security-aware review required. | +| Publication | Changes future site generation or navigation assumptions. | Documentation owner review required. | + +## Revision Workflow + +```mermaid +flowchart TD + A[Identify needed revision] --> B[Open issue or PR] + B --> C{Governance impact?} + C -- Yes --> D[Request maintainer or governance review] + C -- No --> E[Standard documentation review] + D --> F[Revise handbook] + E --> F + F --> G[Validate links and formatting] + G --> H[Merge] + H --> I[Update revision history] +``` + +## Revision Entry Format + +Use this format for substantial handbook changes: + +```markdown +| Date | Version or PR | Change | Reason | Owner | +| --- | --- | --- | --- | --- | +| 2026-08-05 | PR #123 | Added release management chapter. | Defined COSDS release governance. | NTARI maintainers | +``` + +If the repository does not yet use versioned handbook releases, reference the +pull request or commit that introduced the change. + +## Current Revision Log + +| Date | Version or reference | Change | Reason | Owner | +| --- | --- | --- | --- | --- | +| 2026-08-05 | Initial COSDS handbook authoring | Authored governance and onboarding chapters. | Establish production-ready COSDS engineering governance. | NTARI maintainers | + +## Change Review Checklist + +Before merging handbook revisions, confirm: + +- The change has a clear reason. +- Related chapters are updated or linked. +- Internal links resolve. +- No outdated placeholder text remains in edited production chapters. +- Governance, security, or licensing changes have appropriate review. +- Examples and checklists still match current practice. +- The revision history is updated for substantive changes. + +## Versioning the Handbook + +NTARI may later choose to version the handbook. Versioning is useful when: + +- External contributors rely on stable published guidance. +- Docusaurus publication creates public documentation snapshots. +- Governance or compliance reviews require traceable policy versions. +- Major process changes need migration notes. + +Until a versioning model is approved, pull request and commit references are the +source of truth for handbook history. + +## Archiving Superseded Guidance + +Do not leave contradictory guidance in active handbook pages. When guidance is +superseded: + +1. Update the active page. +2. Link to the new standard where useful. +3. Capture the reason in the revision log or pull request. +4. Archive historical context only if it remains valuable. + +## Revision Ownership + +| Area | Recommended reviewer | +| --- | --- | +| GitHub workflow and pull requests | Repository maintainers | +| Security standards | Security contact or maintainer | +| Release management | Maintainer and technical lead | +| Volunteer onboarding | Project coordinator or maintainer | +| Professional conduct | Governance owner or maintainer | +| Documentation standards | Documentation maintainer | + +## Related Chapters + +- [Continuous Improvement](21-continuous-improvement.md) +- [Repository Checklist](22-repository-checklist.md) +- [Volunteer Onboarding Checklist](23-volunteer-onboarding-checklist.md) +- [Engineering Escalation](18-engineering-escalation.md) +- [Release Management](19-release-management.md)