From 3e4c01626b0c77c7e44968e6d23dace3bc4d1089 Mon Sep 17 00:00:00 2001 From: Calvin Secrest Date: Tue, 4 Aug 2026 18:12:09 -0400 Subject: [PATCH] Author first ten engineering handbook chapters --- .editorconfig | 16 ++ .github/ISSUE_TEMPLATE/bug_report.yml | 43 ++++ .../documentation_improvement.yml | 35 ++++ .github/ISSUE_TEMPLATE/engineering_rfc.yml | 41 ++++ .github/ISSUE_TEMPLATE/feature_request.yml | 34 ++++ .github/PULL_REQUEST_TEMPLATE.md | 27 +++ .github/workflows/broken-link-check.yml | 33 +++ .github/workflows/markdown-lint.yml | 29 +++ .github/workflows/spellcheck.yml | 35 ++++ .gitignore | 25 +++ CODEOWNERS | 9 + CODE_OF_CONDUCT.md | 75 +++++++ CONTRIBUTING.md | 33 +++ README.md | 37 ++-- REPOSITORY_READINESS_REPORT.md | 188 ++++++++++++++++++ SECURITY.md | 27 +++ docs/engineering-handbook/01-purpose.md | 125 ++++++++++++ .../02-engineering-principles.md | 125 ++++++++++++ .../03-engineering-roles.md | 149 ++++++++++++++ .../04-communication-standards.md | 136 +++++++++++++ .../05-github-workflow.md | 150 ++++++++++++++ .../06-branching-strategy.md | 136 +++++++++++++ .../07-commit-message-standards.md | 146 ++++++++++++++ .../08-pull-request-process.md | 160 +++++++++++++++ .../09-code-review-standards.md | 156 +++++++++++++++ .../10-repository-standards.md | 169 ++++++++++++++++ .../11-documentation-standards.md | 17 ++ .../12-ci-cd-standards.md | 17 ++ .../13-security-standards.md | 17 ++ .../14-issue-management.md | 17 ++ .../15-project-documentation.md | 17 ++ .../16-volunteer-expectations.md | 17 ++ .../17-professional-conduct.md | 17 ++ .../18-engineering-escalation.md | 17 ++ .../19-release-management.md | 17 ++ .../20-engineering-metrics.md | 17 ++ .../21-continuous-improvement.md | 17 ++ .../22-repository-checklist.md | 17 ++ .../23-volunteer-onboarding-checklist.md | 17 ++ .../24-revision-history.md | 17 ++ .../25-jfa-engineering-principles.md | 17 ++ .../26-github-governance.md | 17 ++ .../27-cloud-infrastructure-standards.md | 17 ++ 43 files changed, 2404 insertions(+), 24 deletions(-) create mode 100644 .editorconfig create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation_improvement.yml create mode 100644 .github/ISSUE_TEMPLATE/engineering_rfc.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/broken-link-check.yml create mode 100644 .github/workflows/markdown-lint.yml create mode 100644 .github/workflows/spellcheck.yml create mode 100644 .gitignore create mode 100644 CODEOWNERS create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 REPOSITORY_READINESS_REPORT.md create mode 100644 SECURITY.md create mode 100644 docs/engineering-handbook/01-purpose.md create mode 100644 docs/engineering-handbook/02-engineering-principles.md create mode 100644 docs/engineering-handbook/03-engineering-roles.md create mode 100644 docs/engineering-handbook/04-communication-standards.md create mode 100644 docs/engineering-handbook/05-github-workflow.md create mode 100644 docs/engineering-handbook/06-branching-strategy.md create mode 100644 docs/engineering-handbook/07-commit-message-standards.md create mode 100644 docs/engineering-handbook/08-pull-request-process.md create mode 100644 docs/engineering-handbook/09-code-review-standards.md create mode 100644 docs/engineering-handbook/10-repository-standards.md create mode 100644 docs/engineering-handbook/11-documentation-standards.md create mode 100644 docs/engineering-handbook/12-ci-cd-standards.md create mode 100644 docs/engineering-handbook/13-security-standards.md create mode 100644 docs/engineering-handbook/14-issue-management.md create mode 100644 docs/engineering-handbook/15-project-documentation.md create mode 100644 docs/engineering-handbook/16-volunteer-expectations.md create mode 100644 docs/engineering-handbook/17-professional-conduct.md create mode 100644 docs/engineering-handbook/18-engineering-escalation.md create mode 100644 docs/engineering-handbook/19-release-management.md create mode 100644 docs/engineering-handbook/20-engineering-metrics.md create mode 100644 docs/engineering-handbook/21-continuous-improvement.md create mode 100644 docs/engineering-handbook/22-repository-checklist.md create mode 100644 docs/engineering-handbook/23-volunteer-onboarding-checklist.md create mode 100644 docs/engineering-handbook/24-revision-history.md create mode 100644 docs/engineering-handbook/25-jfa-engineering-principles.md create mode 100644 docs/engineering-handbook/26-github-governance.md create mode 100644 docs/engineering-handbook/27-cloud-infrastructure-standards.md diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..e27eb6e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +# EditorConfig keeps formatting consistent across editors. +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false + +[Makefile] +indent_style = tab diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..f3be620 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,43 @@ +name: Bug Report +description: Report a repository, workflow, or documentation defect. +title: "Bug: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thank you for helping improve the NTARI Developer Portal. Please provide enough detail for maintainers to reproduce or verify the issue. + - type: textarea + id: problem + attributes: + label: Problem + description: What is broken or behaving unexpectedly? + placeholder: Describe the issue clearly. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What should happen instead? + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: Provide steps, links, file paths, or screenshots when relevant. + placeholder: | + 1. Go to ... + 2. Open ... + 3. Observe ... + validations: + required: false + - type: textarea + id: context + attributes: + label: Additional Context + description: Add any other relevant details. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/documentation_improvement.yml b/.github/ISSUE_TEMPLATE/documentation_improvement.yml new file mode 100644 index 0000000..09dddd4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation_improvement.yml @@ -0,0 +1,35 @@ +name: Documentation Improvement +description: Request a clarification, correction, or future documentation topic. +title: "Docs: " +labels: + - documentation +body: + - type: textarea + id: location + attributes: + label: Documentation Location + description: Link the page, file, heading, or proposed location. + placeholder: docs/engineering-handbook/... + validations: + required: false + - type: textarea + id: improvement + attributes: + label: Requested Improvement + description: What should be clarified, corrected, or added? + validations: + required: true + - type: textarea + id: rationale + attributes: + label: Rationale + description: Why is this change useful or necessary? + validations: + required: true + - type: textarea + id: notes + attributes: + label: Additional Notes + description: Add references, examples, or related discussions. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/engineering_rfc.yml b/.github/ISSUE_TEMPLATE/engineering_rfc.yml new file mode 100644 index 0000000..6f083b2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/engineering_rfc.yml @@ -0,0 +1,41 @@ +name: Engineering RFC +description: Propose a significant engineering process, architecture, or governance decision. +title: "RFC: " +labels: + - rfc +body: + - type: textarea + id: summary + attributes: + label: Summary + description: Provide a concise overview of the proposal. + validations: + required: true + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem or opportunity does this RFC address? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposal + description: Describe the proposed decision, process, or standard. + validations: + required: true + - type: textarea + id: impact + attributes: + label: Impact + description: Who or what would be affected by this proposal? + validations: + required: true + - type: textarea + id: open_questions + attributes: + label: Open Questions + description: List unresolved questions, risks, or decisions needed. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..fad0e2e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,34 @@ +name: Feature Request +description: Suggest a repository capability, workflow, or documentation enhancement. +title: "Feature: " +labels: + - enhancement +body: + - type: textarea + id: summary + attributes: + label: Summary + description: What capability or improvement are you proposing? + validations: + required: true + - type: textarea + id: motivation + attributes: + label: Motivation + description: Why would this be valuable for NTARI maintainers or contributors? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed Approach + description: Describe the expected behavior, workflow, or implementation direction. + validations: + required: false + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: List alternatives or tradeoffs if applicable. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..b84a81c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,27 @@ +## Summary + + + +## Type of Change + +- [ ] Documentation update +- [ ] Repository configuration +- [ ] Governance or process update +- [ ] Engineering RFC +- [ ] Other maintenance + +## Related Issues or RFCs + + + +## Review Checklist + +- [ ] The change is scoped and reviewable. +- [ ] Markdown renders correctly on GitHub. +- [ ] Links are valid or intentionally pending. +- [ ] Spelling and terminology have been reviewed. +- [ ] No confidential, private, or security-sensitive information is included. + +## Additional Notes + + diff --git a/.github/workflows/broken-link-check.yml b/.github/workflows/broken-link-check.yml new file mode 100644 index 0000000..80aa6e7 --- /dev/null +++ b/.github/workflows/broken-link-check.yml @@ -0,0 +1,33 @@ +name: Broken Link Check + +on: + pull_request: + paths: + - "**/*.md" + - ".github/workflows/broken-link-check.yml" + push: + branches: + - main + paths: + - "**/*.md" + - ".github/workflows/broken-link-check.yml" + schedule: + - cron: "0 12 * * 1" + +permissions: + contents: read + +jobs: + link-check: + name: Check Markdown Links + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Run Lychee link checker + uses: lycheeverse/lychee-action@v2 + with: + args: --verbose --no-progress "**/*.md" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..4e182ef --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,29 @@ +name: Markdown Lint + +on: + pull_request: + paths: + - "**/*.md" + - ".github/workflows/markdown-lint.yml" + push: + branches: + - main + paths: + - "**/*.md" + - ".github/workflows/markdown-lint.yml" + +permissions: + contents: read + +jobs: + markdown-lint: + name: Lint Markdown + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v19 + with: + globs: "**/*.md" diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml new file mode 100644 index 0000000..47b58b6 --- /dev/null +++ b/.github/workflows/spellcheck.yml @@ -0,0 +1,35 @@ +name: Spellcheck + +on: + pull_request: + paths: + - "**/*.md" + - ".github/workflows/spellcheck.yml" + push: + branches: + - main + paths: + - "**/*.md" + - ".github/workflows/spellcheck.yml" + +permissions: + contents: read + +jobs: + spellcheck: + name: Check Spelling + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - name: Install codespell + run: python -m pip install --upgrade codespell + + - name: Run codespell + run: codespell --skip=".git" --ignore-words-list="NTARI,JFA" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d21d771 --- /dev/null +++ b/.gitignore @@ -0,0 +1,25 @@ +# Operating system files +.DS_Store +Thumbs.db + +# Editor and IDE files +.vscode/ +.idea/ +*.swp +*.swo + +# Logs and temporary files +*.log +*.tmp +*.temp + +# Dependency directories and generic build output +node_modules/ +dist/ +build/ +.cache/ + +# Local environment files +.env +.env.* +!.env.example diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..aea1150 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,9 @@ +# Placeholder CODEOWNERS for the NTARI Developer Portal. +# Replace these entries with the appropriate NTARI GitHub teams or maintainers. + +* @NTARI-RAND/maintainers +/README.md @NTARI-RAND/docs-maintainers +/CONTRIBUTING.md @NTARI-RAND/docs-maintainers +/CODE_OF_CONDUCT.md @NTARI-RAND/maintainers +/SECURITY.md @NTARI-RAND/maintainers +/LICENSE @NTARI-RAND/maintainers diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..661a92f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,75 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people. +- Being respectful of differing opinions, viewpoints, and experiences. +- Giving and gracefully accepting constructive feedback. +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience. +- Focusing on what is best not just for us as individuals, but for the overall community. + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind. +- Trolling, insulting or derogatory comments, and personal or political attacks. +- Public or private harassment. +- Publishing others' private information, such as a physical or email address, without their explicit permission. +- Other conduct which could reasonably be considered inappropriate in a professional setting. + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting through an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement through the reporting channels designated by NTARI. All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact:** Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence:** A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact:** A violation through a single incident or series of actions. + +**Consequence:** A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact:** A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence:** A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact:** Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence:** A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at . + +Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fca81b1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing to the NTARI Developer Portal + +Thank you for helping improve the NTARI Developer Portal. This repository is maintained by the Network Theory Applied Research Institute (NTARI) as the authoritative home for NTARI developer-facing documentation. + +## What to Contribute + +At this stage, contributions should focus on repository governance, documentation structure proposals, typo fixes, clarity improvements, and issue reports. Full documentation pages and handbook content should not be added until NTARI opens the relevant documentation area for review. + +## Documentation Contribution Guidelines + +- Use clear, concise Markdown that renders well on GitHub. +- Keep pull requests focused on a single purpose. +- Prefer small, reviewable changes over large unstructured updates. +- Avoid adding confidential, private, or security-sensitive information. +- Link related issues, discussions, or decisions when available. +- Do not introduce documentation pages before the relevant section has been approved for creation. + +## Opening Issues + +Use GitHub issues to report documentation gaps, broken links, inaccurate wording, repository configuration problems, or proposed improvements. Include enough context for maintainers to understand the requested change. + +## Pull Request Expectations + +A good documentation pull request should include: + +1. A short summary of the change. +2. The reason the change is needed. +3. Any related issue or discussion links. +4. Confirmation that the Markdown has been reviewed for readability. + +## Licensing + +By contributing to this repository, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0, as described in [`LICENSE`](LICENSE). diff --git a/README.md b/README.md index ee7a20a..810c7e7 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,29 @@ # NTARI Developer Portal -The NTARI Developer Portal is the central documentation repository for engineering, architecture, operations, and contributor guidance across NTARI projects. +The NTARI Developer Portal is the official documentation repository maintained by the Network Theory Applied Research Institute (NTARI). -## Purpose +This repository will become the authoritative source for NTARI developer-facing documentation, including future engineering guidance, architecture references, operational notes, project documentation, and contributor resources. The portal is currently maintained as a Markdown-first GitHub repository and may later be published with a dedicated documentation platform such as Docusaurus. -This repository contains: +## Current Scope -- Engineering Handbook -- Janus Facing Architecture (JFA) -- GitHub Governance -- Cloud & Infrastructure Standards -- Volunteer Onboarding -- RFCs -- Operations Documentation +This repository currently defines the governance and contribution foundation for the Developer Portal. Documentation pages have not been created yet. -## Projects +## Maintainer -The standards in this repository apply to: +Documentation in this repository is maintained by NTARI. -- SoHoLink -- Agrinet -- Tell -- Janusand -- NTARI OS -- Future NTARI projects +## Contributing -## Getting Started +Documentation contributions are welcome through GitHub issues and pull requests. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) before proposing changes. -New contributors should begin with: +## Code of Conduct -docs/engineering-handbook/ +Participation in this repository is governed by the Contributor Covenant Code of Conduct. See [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). -## Contributing +## Security and Repository Issues -See CONTRIBUTING.md. +To report documentation integrity problems, repository configuration concerns, or potential security issues, see [`SECURITY.md`](SECURITY.md). ## License -See LICENSE. +This repository is licensed under the GNU Affero General Public License v3.0. See [`LICENSE`](LICENSE). diff --git a/REPOSITORY_READINESS_REPORT.md b/REPOSITORY_READINESS_REPORT.md new file mode 100644 index 0000000..2e42e72 --- /dev/null +++ b/REPOSITORY_READINESS_REPORT.md @@ -0,0 +1,188 @@ +# Repository Readiness Report + +## Scope + +This report reviews the NTARI Developer Portal repository for open-source +readiness. It evaluates structure, Markdown conventions, community health, +GitHub compatibility, future Docusaurus compatibility, scalability, +accessibility, and cleanliness. + +This report does not add handbook or documentation-body content. + +## Executive Summary + +The repository is ready as an early Markdown-first open-source documentation +foundation. It has clear governance files, issue and pull request templates, +placeholder Engineering Handbook pages, and GitHub Actions workflows for basic +Markdown quality gates. + +The repository should remain lightweight until NTARI approves substantive +handbook content. The main improvements to prioritize next are ownership +finalization, lint configuration tuning, link-check policy decisions, and future +Docusaurus planning files when the project is ready for publication tooling. + +## Review Areas + +### Folder Organization + +Status: Ready with minor future improvements. + +Findings: + +- Root governance files are easy to discover. +- GitHub configuration is organized under `.github/`. +- Engineering Handbook placeholders are isolated under + `docs/engineering-handbook/`. +- No unrelated application, build, or Docusaurus folders are present. + +Recommended improvements: + +- Add top-level documentation index files only when NTARI is ready to define + navigation. +- Add future documentation areas incrementally instead of creating broad empty + trees. + +### Markdown Structure + +Status: Ready for placeholders. + +Findings: + +- Markdown files use clear headings and consistent placeholder structure. +- Handbook files avoid substantive handbook content. +- Governance files are readable in GitHub's Markdown renderer. + +Recommended improvements: + +- Add a Markdown lint configuration once NTARI agrees on line length, + heading-style, and list-format rules. +- Add front matter only if and when Docusaurus or another static site generator + is introduced. + +### Community Health Files + +Status: Ready with placeholder ownership. + +Findings: + +- `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, + `LICENSE`, and `CODEOWNERS` are present. +- Contributor Covenant 2.1 language is included. +- Security guidance covers documentation and repository integrity concerns. +- CODEOWNERS uses placeholder NTARI teams. + +Recommended improvements: + +- Replace placeholder CODEOWNERS teams with confirmed GitHub teams. +- Add public contact or private reporting details to `SECURITY.md` when NTARI + has approved disclosure channels. +- Add issue labels in GitHub to match the configured issue forms. + +### GitHub Compatibility + +Status: Ready for GitHub-hosted collaboration. + +Findings: + +- Pull request and issue templates are in GitHub-supported locations. +- Issue templates use GitHub Issue Forms YAML. +- GitHub Actions workflows are present for Markdown linting, link checking, + and spellcheck. +- Workflow permissions are read-only by default. + +Recommended improvements: + +- Confirm that referenced GitHub teams exist before enforcing CODEOWNERS. +- Confirm third-party GitHub Actions are approved by NTARI governance. +- Consider pinning actions by full commit SHA for stricter supply-chain control. + +### Future Docusaurus Compatibility + +Status: Compatible with future adoption. + +Findings: + +- Markdown-first files under `docs/` are compatible with a future Docusaurus + migration path. +- Numeric filename prefixes can support stable ordering in generated sidebars. +- No Docusaurus dependency, configuration, or generated output is present. + +Recommended improvements: + +- Add Docusaurus only in a dedicated future change. +- Decide whether future pages should use front matter for sidebar labels, + slugs, tags, and descriptions. +- Reserve generated output directories in `.gitignore` only when tooling is + actually introduced. + +### Scalability + +Status: Good initial foundation. + +Findings: + +- The repository separates governance, GitHub configuration, and handbook + placeholders. +- Numbered handbook files support predictable growth. +- Issue forms separate different intake paths for maintainers. + +Recommended improvements: + +- Define documentation ownership by section when real content begins. +- Add templates for RFCs, runbooks, and decision records only when NTARI is + ready to accept those document types. +- Consider adding a changelog or revision process after the handbook receives + substantive content. + +### Accessibility + +Status: Ready for text-first content. + +Findings: + +- Current content is text-based and readable without images or scripts. +- No inaccessible diagrams, media, or interactive components are present. +- Issue and pull request forms use clear labels and descriptions. + +Recommended improvements: + +- Require alt text for future images and diagrams. +- Prefer descriptive link text in future documentation. +- Add accessibility checks to documentation review guidance before publishing + richer visual content. + +### Repository Cleanliness + +Status: Clean. + +Findings: + +- The working tree was clean before this report was added. +- The repository has no empty tracked directories. +- No generated build artifacts are tracked. +- `.gitignore` covers common local files, dependency folders, caches, and build + output. + +Recommended improvements: + +- Keep generated files out of version control. +- Avoid adding broad placeholder trees before navigation and ownership are + defined. +- Periodically review workflow logs after CI starts running on pull requests. + +## Overall Readiness Assessment + +The repository is ready for early open-source collaboration and controlled +Markdown-first documentation development. It is not yet ready for a public +published documentation site because navigation, ownership, content review +policy, and publication tooling have not been finalized. + +## Prioritized Improvements + +1. Confirm and replace placeholder CODEOWNERS teams. +2. Configure repository labels to match issue forms. +3. Add NTARI-approved sensitive issue reporting details to `SECURITY.md`. +4. Decide Markdown lint rules and add a repository lint configuration. +5. Review third-party GitHub Actions policy and pin actions if required. +6. Define a future Docusaurus migration plan before adding Docusaurus files. +7. Add accessibility requirements before accepting images, diagrams, or media. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..1c6236a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,27 @@ +# Security Policy + +NTARI maintains this repository as the authoritative home for Developer Portal documentation and related repository governance files. + +## Reporting Documentation and Repository Issues + +Please report issues that may affect the integrity, safety, or reliability of this repository. Examples include: + +- Incorrect security-sensitive documentation. +- Accidental exposure of private or confidential information. +- Suspicious links or malicious content in documentation. +- Repository configuration problems that could affect reviews, ownership, or publishing. +- Concerns involving licensing, attribution, or contributor trust. + +## How to Report + +If the issue is not sensitive, open a GitHub issue with a clear description and supporting context. + +If the issue is sensitive or could create risk if publicly disclosed, do not open a public issue. Instead, contact the NTARI maintainers through the private reporting channel designated by the organization. If a GitHub private vulnerability reporting workflow is enabled for this repository, use that workflow. + +## Response Expectations + +NTARI maintainers will review reports, determine the appropriate remediation path, and follow up when more information is needed. Response times may vary while this repository is in its initial setup phase. + +## Scope + +This policy applies to documentation, repository configuration, contribution workflows, and files maintained in this repository. diff --git a/docs/engineering-handbook/01-purpose.md b/docs/engineering-handbook/01-purpose.md new file mode 100644 index 0000000..3b13fa4 --- /dev/null +++ b/docs/engineering-handbook/01-purpose.md @@ -0,0 +1,125 @@ +# Purpose + +## Overview + +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. + +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. + +## Handbook Goals + +The handbook exists to make NTARI engineering work: + +- **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 new file mode 100644 index 0000000..7fc5165 --- /dev/null +++ b/docs/engineering-handbook/02-engineering-principles.md @@ -0,0 +1,125 @@ +# Engineering Principles + +## Overview + +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. + +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. + +## Core Principles + +| 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. | + +## 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 new file mode 100644 index 0000000..815fc4c --- /dev/null +++ b/docs/engineering-handbook/03-engineering-roles.md @@ -0,0 +1,149 @@ +# Engineering Roles + +## Overview + +COSDS is designed for coordinated volunteer participation. Clear roles help +contributors understand decision rights, review expectations, and escalation +paths without requiring private organizational knowledge. + +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. + +## Role Summary + +| 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. | + +## 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 new file mode 100644 index 0000000..55e59d5 --- /dev/null +++ b/docs/engineering-handbook/04-communication-standards.md @@ -0,0 +1,136 @@ +# Communication Standards + +## Overview + +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. + +All communication must follow the repository +[`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md). + +## Communication Principles + +| 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. | + +## 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 new file mode 100644 index 0000000..85672b9 --- /dev/null +++ b/docs/engineering-handbook/05-github-workflow.md @@ -0,0 +1,150 @@ +# GitHub Workflow + +## Overview + +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. + +This workflow is designed for volunteers. It favors explicit context, small +changes, and asynchronous review. + +## Standard Workflow + +```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 + + 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 new file mode 100644 index 0000000..88e2565 --- /dev/null +++ b/docs/engineering-handbook/06-branching-strategy.md @@ -0,0 +1,136 @@ +# Branching Strategy + +## Overview + +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. + +The strategy favors clarity over complexity. Long-running branches and hidden +integration work make volunteer collaboration harder and should be avoided. + +## Default Branch + +The default branch is the stable integration branch for accepted work. In most +NTARI repositories this branch is expected to be `main`. + +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 new file mode 100644 index 0000000..dd21abc --- /dev/null +++ b/docs/engineering-handbook/07-commit-message-standards.md @@ -0,0 +1,146 @@ +# Commit Message Standards + +## Overview + +Commit messages are part of the engineering record. They help reviewers, +maintainers, release authors, and future contributors understand why a change +exists. + +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. + +## Format + +```text +: +``` + +Optional extended format: + +```text +(): + + + +