Skip to content

Add repository governance, contribution handbook, templates, and docs-quality CI #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
csecrestjr merged 2 commits into from
Aug 5, 2026
Merged

Add repository governance, contribution handbook, templates, and docs-quality CI #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9c509b0
Author COSDS governance handbook chapters
csecrestjr Aug 5, 2026
3c1563b
Merge branch 'main' into codex/create-initial-repository-structure-fo…
csecrestjr Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 137 additions & 10 deletions docs/engineering-handbook/18-engineering-escalation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
154 changes: 144 additions & 10 deletions docs/engineering-handbook/19-release-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading