Skip to content

Initial repository governance, engineering handbook, and documentation CI workflows #7

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 4, 2026
Merged

Initial repository governance, engineering handbook, and documentation CI workflows #7

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
3e4c016
Author first ten engineering handbook chapters
csecrestjr Aug 4, 2026
9f65886
Merge branch 'main' into codex/create-initial-repository-structure-fo…
csecrestjr Aug 4, 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
128 changes: 118 additions & 10 deletions docs/engineering-handbook/01-purpose.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
128 changes: 118 additions & 10 deletions docs/engineering-handbook/02-engineering-principles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading