diff --git a/docs/engineering-handbook/11-documentation-standards.md b/docs/engineering-handbook/11-documentation-standards.md index 7a7db4a..097e4bf 100644 --- a/docs/engineering-handbook/11-documentation-standards.md +++ b/docs/engineering-handbook/11-documentation-standards.md @@ -1,17 +1,187 @@ # Documentation Standards -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on documentation standards. +Documentation is an engineering deliverable in COSDS. It explains how people +understand, use, operate, review, and maintain NTARI systems. Documentation must +be accurate, accessible, version-controlled, and reviewable through the same +GitHub workflow used for code. -## Placeholder Sections +These standards apply to handbook chapters, project documentation, repository +README files, runbooks, RFCs, architecture notes, and contributor guidance. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Documentation Principles -## Status +| Principle | Practice | +| --- | --- | +| Write for the next contributor | Assume the reader was not present for prior discussions. | +| Keep docs close to the work | Place documentation near the repository, feature, or process it describes. | +| Prefer explicit structure | Use headings, lists, tables, and examples to reduce ambiguity. | +| Keep links durable | Prefer relative internal links and stable public references. | +| Document decisions | Capture the reason for important choices, not only the final state. | +| Review documentation like code | Check accuracy, scope, accessibility, and maintainability. | -Content coming soon. +## Required Qualities + +Good NTARI documentation is: + +- **Accurate**: it matches the current repository behavior or clearly describes + future work. +- **Actionable**: it helps the reader complete a task or make a decision. +- **Accessible**: it uses plain language, descriptive links, and text + alternatives for visual material. +- **Traceable**: it links to related issues, pull requests, RFCs, or chapters. +- **Maintainable**: it has a clear owner or review path. +- **License-aware**: copied material, examples, and assets respect AGPL-3.0 and + third-party licensing obligations. + +## Document Types + +| Type | Purpose | Typical location | +| --- | --- | --- | +| README | Repository introduction and navigation | Repository root | +| Handbook chapter | Shared engineering policy or process | `docs/engineering-handbook/` | +| Project documentation | Project-specific overview and usage | Project repository or project docs area | +| Runbook | Operational procedure | Operations documentation area | +| RFC | Proposal for significant change | RFC documentation area or issue form | +| Decision record | Captures a durable technical decision | Architecture or project docs area | + +See [Project Documentation](15-project-documentation.md) for project-level +expectations. + +## Markdown Structure + +Use GitHub-flavored Markdown. Prefer predictable structure: + +```markdown +# Page Title + +## Overview + +A short explanation of what the page covers. + +## Requirements + +- Requirement one. +- Requirement two. + +## Examples + +Concrete examples that contributors can adapt. + +## Related Chapters + +- Related page link +``` + +Rules: + +- Use one top-level `#` heading per page. +- Use sentence-style headings. +- Keep sections focused. +- Use fenced code blocks with language identifiers when practical. +- Use tables for comparisons, ownership, status, or checklists. +- Avoid unexplained acronyms. + +## Examples + +Good example: + +```markdown +## Validation + +Run the following before requesting review: + +- `npm test` +- `npm run lint` +- Review rendered Markdown for broken formatting. +``` + +Poor example: + +```markdown +## Stuff + +Do the normal checks. +``` + +The good example is specific, actionable, and reviewable. The poor example +requires private knowledge. + +## Internal Links + +Use relative links for repository files: + +```markdown +See [Pull Request Process](08-pull-request-process.md). +``` + +Avoid absolute GitHub links for files in the same repository unless the link +must point to a specific historical revision. + +Internal links should be checked before merge. For pull request guidance, see +[Pull Request Process](08-pull-request-process.md). + +## External Links + +External links should be: + +- Publicly accessible. +- Stable enough for long-term documentation. +- Relevant to the surrounding text. +- Described with meaningful link text. + +Avoid linking to private documents, expiring chat threads, or inaccessible +resources from public documentation. + +## Accessibility Standards + +Documentation should be usable by contributors with different tools, abilities, +and network conditions. + +Checklist: + +- Use descriptive link text. +- Provide alt text for images. +- Do not rely on color alone to convey meaning. +- Provide text summaries for diagrams. +- Use tables only when tabular structure improves comprehension. +- Keep sentences direct and avoid unnecessary jargon. + +Mermaid diagrams are useful when they clarify flow, but the surrounding text +must still explain the process. + +## Review Checklist + +Before merging documentation changes, confirm: + +- The page has a clear purpose. +- The content is accurate for the current repository state. +- Internal links resolve. +- Examples are safe to copy. +- Commands are fenced and include language identifiers where helpful. +- Accessibility expectations are met. +- Licensing and attribution are appropriate. +- Related handbook chapters are linked. + +## Maintenance Expectations + +Documentation should be updated when: + +- A workflow changes. +- A command changes. +- A repository structure changes. +- A policy changes. +- Review comments show repeated confusion. +- A contributor needs private explanation to complete a public task. + +Documentation debt should be captured as issues rather than left in untracked +notes. + +## 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/12-ci-cd-standards.md b/docs/engineering-handbook/12-ci-cd-standards.md index e6ed038..9b144fc 100644 --- a/docs/engineering-handbook/12-ci-cd-standards.md +++ b/docs/engineering-handbook/12-ci-cd-standards.md @@ -1,17 +1,158 @@ # CI/CD Standards -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on ci/cd standards. +Continuous integration and continuous delivery help NTARI repositories stay +reviewable, reproducible, and safe. In COSDS, automation should support +contributors without hiding important decisions from maintainers. -## Placeholder Sections +CI/CD standards apply to GitHub Actions workflows, status checks, build scripts, +test commands, release automation, and deployment gates. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Goals -## Status +CI/CD should: -Content coming soon. +- Catch errors before merge. +- Provide fast feedback to contributors. +- Use least-privilege permissions. +- Make failures actionable. +- Avoid leaking secrets or private data. +- Support AGPL-3.0 source availability and reproducible release practices. + +## Workflow Design Principles + +| Principle | Practice | +| --- | --- | +| Keep checks relevant | Run workflows only for paths that can affect them. | +| Fail clearly | Error output should tell contributors what to fix. | +| Minimize permissions | Use read-only permissions unless write access is required. | +| Prefer reproducibility | Pin runtime versions and document build commands. | +| Separate concerns | Keep lint, test, security, and release workflows distinct. | +| Avoid surprise deployment | Deploy only from protected branches or approved release workflows. | + +## Recommended Workflow Categories + +| Workflow | Purpose | Example trigger | +| --- | --- | --- | +| Markdown lint | Enforce documentation style | Pull requests changing `*.md` | +| Link check | Detect broken documentation links | Pull requests and scheduled runs | +| Spellcheck | Catch spelling and terminology errors | Pull requests changing docs | +| Unit tests | Validate code behavior | Pull requests changing source files | +| Security scan | Detect dependency or configuration risk | Pull requests and scheduled runs | +| Release | Build and publish artifacts | Tags or maintainer-approved dispatch | + +## GitHub Actions Standards + +GitHub Actions workflows should: + +- Declare explicit `permissions`. +- Use descriptive workflow and job names. +- Use maintained actions from trusted sources. +- Avoid secrets in pull request workflows from forks unless explicitly safe. +- Use path filters when appropriate. +- Keep deployment separate from validation. + +Example read-only workflow header: + +```yaml +name: Markdown Lint + +on: + pull_request: + paths: + - "**/*.md" + +permissions: + contents: read +``` + +## Secrets and Sensitive Data + +CI must never print secrets, tokens, private keys, or sensitive repository +configuration. + +Checklist: + +- Store secrets only in approved GitHub secret stores or external secret + management systems. +- Do not echo secrets in logs. +- Do not run untrusted pull request code with privileged credentials. +- Redact sensitive values from debug output. +- Rotate credentials if accidental exposure is suspected. + +Report concerns through [`../../SECURITY.md`](../../SECURITY.md). + +## Status Checks + +Maintainers should require checks that match repository risk. + +For documentation repositories: + +- Markdown lint. +- Broken link check. +- Spellcheck. + +For software repositories: + +- Formatting or linting. +- Unit tests. +- Integration tests when practical. +- Dependency or vulnerability scanning. +- Build verification. + +Required checks should be stable. If a check is flaky, fix or tune it before +making it a hard merge requirement. + +## CI Failure Triage + +```mermaid +flowchart TD + A[CI failure] --> B{Failure reproducible?} + B -- Yes --> C[Fix code, docs, or config] + B -- No --> D[Check external service or flaky test] + D --> E{Flake confirmed?} + E -- Yes --> F[Open issue and tune workflow] + E -- No --> C + C --> G[Push update] + G --> H[Checks pass] +``` + +When CI fails, contributors should include the failing check name and relevant +log excerpt in the pull request discussion if help is needed. + +## Release and Deployment Controls + +Release and deployment automation should be conservative. + +Minimum expectations: + +- Deploy only from protected branches, signed tags, or maintainer-approved + manual workflows. +- Document release commands and rollback steps. +- Separate validation from production deployment. +- Require maintainer review for workflow changes that affect credentials or + publishing. + +See [Release Management](19-release-management.md) when that chapter is +available. + +## Review Checklist + +Before merging CI/CD changes, confirm: + +- Workflow YAML is valid. +- Permissions are least-privilege. +- Triggers are appropriate. +- Secrets are not exposed to untrusted code. +- Failure messages are actionable. +- The workflow does not introduce Docusaurus or other tooling unless approved. +- Documentation explains new commands or checks. + +## Related Chapters + +- [GitHub Workflow](05-github-workflow.md) +- [Pull Request Process](08-pull-request-process.md) +- [Code Review Standards](09-code-review-standards.md) +- [Repository Standards](10-repository-standards.md) +- [Security Standards](13-security-standards.md) diff --git a/docs/engineering-handbook/13-security-standards.md b/docs/engineering-handbook/13-security-standards.md index 1ca1612..cc4554f 100644 --- a/docs/engineering-handbook/13-security-standards.md +++ b/docs/engineering-handbook/13-security-standards.md @@ -1,17 +1,136 @@ # Security Standards -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on security standards. +Security is a shared engineering responsibility in COSDS. Every contributor must +help protect users, maintainers, infrastructure, documentation integrity, and +open-source trust. -## Placeholder Sections +This chapter defines baseline security expectations for NTARI engineering work. +Sensitive reports must follow the repository security policy in +[`../../SECURITY.md`](../../SECURITY.md). -- Overview -- Scope -- Standards -- Responsibilities -- References +## Security Principles -## Status +| Principle | Meaning | +| --- | --- | +| Least privilege | Grant only the access required for the task. | +| Secure by default | Avoid unsafe defaults that require users to opt into safety. | +| Defense in depth | Use multiple controls rather than relying on one mechanism. | +| Public does not mean careless | Open-source work still requires careful handling of sensitive data. | +| Review high-risk changes | Security-relevant changes need explicit review. | +| Prefer traceability | Security decisions should be documented at the appropriate sensitivity level. | -Content coming soon. +## Sensitive Information + +Never commit: + +- Passwords, tokens, API keys, or private keys. +- `.env` files containing real credentials. +- Private infrastructure details that are not approved for publication. +- Personal data that is not required and authorized. +- Vulnerability details that have not been cleared for public disclosure. + +If sensitive information is committed: + +1. Stop sharing the branch or pull request link beyond necessary responders. +2. Notify maintainers using the security reporting path. +3. Rotate the exposed secret or credential. +4. Remove the secret from the repository history if maintainers determine that + history rewriting is required. +5. Document the remediation at the appropriate level. + +## Dependency Security + +Before adding a dependency, ask: + +- Is the dependency necessary? +- Is it maintained? +- Is its license compatible with the repository license? +- Does it introduce known vulnerabilities? +- Does it run code during installation or build? +- Is there a smaller or standard-library alternative? + +Dependency changes should be visible in pull requests and reviewed for license, +security, and maintenance impact. + +## Authentication and Authorization + +Changes involving identity, access, or permissions require careful review. + +Checklist: + +- Authentication failures do not reveal sensitive information. +- Authorization checks happen server-side or in trusted control paths. +- Privilege boundaries are explicit. +- Default roles are least-privilege. +- Administrative actions are auditable. +- Tests cover allowed and denied access paths. + +## Logging and Error Handling + +Logs and errors should help operators without exposing sensitive information. + +Safe logs may include: + +- Request identifiers. +- Non-sensitive status codes. +- High-level operation names. +- Sanitized validation failures. + +Unsafe logs include: + +- Tokens or credentials. +- Full personal records. +- Private keys. +- Raw authorization headers. +- Sensitive infrastructure endpoints. + +## Secure Review Flow + +```mermaid +flowchart LR + A[Identify security-relevant change] --> B[Document risk in PR] + B --> C[Request qualified review] + C --> D{Sensitive details?} + D -- Yes --> E[Use private reporting path] + D -- No --> F[Discuss in PR] + E --> G[Remediate safely] + F --> G + G --> H[Merge after validation] +``` + +## Open-Source and AGPL-3.0 Considerations + +AGPL-3.0 governance affects security and architecture decisions. Contributors +must avoid introducing components with incompatible licenses or unclear source +availability requirements. + +When building network-accessible systems, maintainers should ensure that source +code availability obligations are understood before release or deployment. + +## Security Review Checklist + +Before merging a security-relevant change, confirm: + +- No secrets or private data are included. +- Access control changes are tested. +- Error messages and logs are sanitized. +- Dependencies are necessary and reviewed. +- Configuration defaults are safe. +- Documentation does not expose sensitive procedures. +- A rollback or remediation plan exists for high-risk changes. + +## Incident-Aware Documentation + +Public documentation should explain safe behavior without publishing exploit +instructions or sensitive operational details. When a vulnerability is under +active remediation, coordinate with maintainers before adding public detail. + +## Related Chapters + +- [Engineering Principles](02-engineering-principles.md) +- [Communication Standards](04-communication-standards.md) +- [CI/CD Standards](12-ci-cd-standards.md) +- [Code Review Standards](09-code-review-standards.md) +- [Repository Standards](10-repository-standards.md) diff --git a/docs/engineering-handbook/14-issue-management.md b/docs/engineering-handbook/14-issue-management.md index 5389143..31b2350 100644 --- a/docs/engineering-handbook/14-issue-management.md +++ b/docs/engineering-handbook/14-issue-management.md @@ -1,17 +1,154 @@ # Issue Management -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on issue management. +Issues are the planning and coordination backbone of COSDS. A good issue makes +work understandable, assignable, reviewable, and traceable. Issues should help +volunteers find work and help maintainers keep repository priorities visible. -## Placeholder Sections +## Issue Types -- Overview -- Scope -- Standards -- Responsibilities -- References +| Type | Use for | Template | +| --- | --- | --- | +| Bug | Something is broken or incorrect. | Bug Report | +| Feature | A new capability or enhancement. | Feature Request | +| Documentation | A documentation correction or gap. | Documentation Improvement | +| RFC | A significant engineering or governance proposal. | Engineering RFC | +| Maintenance | Repository cleanup or routine upkeep. | Maintainer-created issue | +| Security | Sensitive or risk-related concern. | Private reporting path when needed | -## Status +Sensitive issues should follow [`../../SECURITY.md`](../../SECURITY.md), not a +public issue. -Content coming soon. +## Good Issue Structure + +A useful issue includes: + +- A concise title. +- Problem statement. +- Context and links. +- Expected outcome. +- Acceptance criteria when known. +- Risk or dependency notes. +- Suggested owner or role when applicable. + +Example: + +```markdown +Title: Docs: clarify pull request validation examples + +Problem: +New contributors are unsure what validation to include for documentation-only +pull requests. + +Expected outcome: +Update the pull request process chapter with examples for documentation, +workflow, and code changes. + +Acceptance criteria: +- Examples are copyable. +- Internal links are valid. +- No placeholder text remains. +``` + +## Labels + +Labels help contributors filter and maintainers triage. + +Recommended labels: + +| Label | Meaning | +| --- | --- | +| `bug` | Incorrect behavior or broken repository function. | +| `documentation` | Documentation work or correction. | +| `enhancement` | New capability or improvement. | +| `rfc` | Proposal requiring broader review. | +| `good first issue` | Suitable for a new contributor. | +| `help wanted` | Maintainers welcome outside contribution. | +| `blocked` | Cannot proceed without a decision or dependency. | +| `security` | Security-relevant issue; use carefully and avoid sensitive details. | +| `maintenance` | Cleanup, configuration, or routine upkeep. | + +## Triage Process + +```mermaid +flowchart TD + A[New issue] --> B[Confirm type] + B --> C[Check for duplicates] + C --> D{Sensitive?} + D -- Yes --> E[Move to security reporting path] + D -- No --> F[Add labels and scope] + F --> G{Ready for work?} + G -- Yes --> H[Assign or mark available] + G -- No --> I[Ask clarifying questions] +``` + +## Acceptance Criteria + +Acceptance criteria define what must be true for the issue to be complete. +They should be specific enough for a reviewer to verify. + +Good acceptance criteria: + +- The broken link is replaced with a valid relative link. +- The pull request template asks authors to describe validation. +- The workflow runs only on Markdown changes. + +Poor acceptance criteria: + +- Make it better. +- Clean this up. +- Improve docs. + +## Assignment and Ownership + +Assignments should reflect active ownership. Do not assign contributors without +confirmation unless repository maintainers have an established process for doing +so. + +If a contributor becomes unavailable, a maintainer may unassign the issue after +leaving a clear status comment. + +## Stale Issues + +Issues may become stale when they no longer reflect current priorities or lack +required information. + +Before closing as stale: + +- Ask whether the issue is still relevant. +- Identify missing information. +- Link replacement issues when applicable. +- Leave a clear closing reason. + +## Linking Issues and Pull Requests + +Pull requests should link related issues using GitHub keywords when appropriate: + +```markdown +Closes #42 +Refs #43 +``` + +Use `Closes` when merging the pull request completes the issue. Use `Refs` when +the pull request is related but does not fully resolve the issue. + +## Issue Management Checklist + +Maintainers should periodically confirm: + +- New issues are triaged. +- Labels are consistent. +- Duplicate issues are linked. +- Blocked issues identify the blocker. +- Security-sensitive issues are not discussed publicly. +- Good first issues are genuinely suitable for new contributors. +- Completed work is closed or linked to merged pull requests. + +## Related Chapters + +- [Communication Standards](04-communication-standards.md) +- [GitHub Workflow](05-github-workflow.md) +- [Pull Request Process](08-pull-request-process.md) +- [Volunteer Expectations](16-volunteer-expectations.md) +- [Engineering RFC](26-github-governance.md) diff --git a/docs/engineering-handbook/15-project-documentation.md b/docs/engineering-handbook/15-project-documentation.md index 692f8ee..188842a 100644 --- a/docs/engineering-handbook/15-project-documentation.md +++ b/docs/engineering-handbook/15-project-documentation.md @@ -1,17 +1,177 @@ # Project Documentation -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on project documentation. +Project documentation explains what a specific NTARI project is, how it works, +how contributors participate, and how maintainers operate it. It should give a +new volunteer enough context to make a safe first contribution without relying +on private knowledge. -## Placeholder Sections +This chapter defines baseline expectations for project-level documentation in +COSDS. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Project Documentation Goals + +Project documentation should answer: + +- What problem does the project solve? +- Who uses or maintains it? +- What is the current maturity level? +- How do contributors set up and validate changes? +- Where are architecture, operations, and security notes? +- What license and governance expectations apply? + +## Recommended Project README Structure + +```markdown +# Project Name + +## Overview ## Status -Content coming soon. +## Getting Started + +## Development + +## Testing + +## Documentation + +## Security + +## Contributing + +## License +``` + +The README should be concise. Detailed procedures should live in dedicated files +when they grow beyond a short section. + +## Required Project Information + +| Section | Purpose | +| --- | --- | +| Overview | Describes the project and audience. | +| Status | Explains maturity, stability, and known limitations. | +| Getting Started | Helps a contributor run or inspect the project. | +| Development | Documents local setup and common commands. | +| Testing | Lists validation commands and expectations. | +| Security | Links to reporting policy and project-specific notes. | +| Contributing | Links to repository contribution guidance. | +| License | States the applicable license and links to `LICENSE`. | + +## Setup Instructions + +Setup instructions should be reproducible. + +Include: + +- Required tools and versions. +- Installation commands. +- Environment variables with safe example values. +- How to run tests or checks. +- Common troubleshooting notes. + +Do not include real credentials or private endpoints. + +Good example: + +````markdown +Copy the example environment file and replace placeholder values with local test +credentials: + +```bash +cp .env.example .env +``` +```` + +## Architecture Notes + +Project documentation should identify major components and boundaries. Use a +Mermaid diagram when it improves understanding. + +```mermaid +flowchart LR + A[Contributor] --> B[GitHub Repository] + B --> C[CI Checks] + B --> D[Project Documentation] + D --> E[Operational Notes] +``` + +The diagram should be accompanied by text so the information remains accessible +outside Mermaid renderers. + +## Operational Notes + +Operational documentation should be separated from basic project introduction. +When operational details are sensitive, document the existence of the process +without exposing private information. + +Include public-safe details such as: + +- Service ownership. +- Support expectations. +- Public status information. +- Non-sensitive runbook links. + +Avoid: + +- Secrets. +- Private infrastructure topology. +- Exploit details. +- Emergency contacts that are not approved for public release. + +## Documentation Ownership + +Every project should identify who can review documentation changes. Ownership +may be expressed through CODEOWNERS, maintainers, or project-specific notes. + +Questions to answer: + +- Who reviews project documentation? +- Who reviews security-sensitive updates? +- Who approves architecture changes? +- Who updates documentation after releases? + +## Documentation Checklist + +Before considering project documentation ready, confirm: + +- The README explains the project clearly. +- Setup instructions work for a new contributor. +- Validation commands are documented. +- Internal links resolve. +- Public documentation does not expose sensitive information. +- License references are accurate. +- Contribution paths are clear. +- Accessibility expectations are met. + +## Relationship to Handbook Chapters + +Project documentation should link back to shared handbook guidance instead of +repeating it. For example: + +- Link to [GitHub Workflow](05-github-workflow.md) for contribution flow. +- Link to [Code Review Standards](09-code-review-standards.md) for review + expectations. +- Link to [Security Standards](13-security-standards.md) for security baseline. +- Link to [Repository Standards](10-repository-standards.md) for repository + structure. + +## Future Docusaurus Compatibility + +If project documentation may later be published through Docusaurus: + +- Use stable filenames. +- Prefer relative links. +- Keep one top-level heading per page. +- Avoid repository-host-specific assumptions when a portable alternative exists. +- Delay front matter until the publishing structure is approved. + +## Related Chapters + +- [Documentation Standards](11-documentation-standards.md) +- [Repository Standards](10-repository-standards.md) +- [Security Standards](13-security-standards.md) +- [Volunteer Expectations](16-volunteer-expectations.md) diff --git a/docs/engineering-handbook/16-volunteer-expectations.md b/docs/engineering-handbook/16-volunteer-expectations.md index 4ae3529..88cf0b3 100644 --- a/docs/engineering-handbook/16-volunteer-expectations.md +++ b/docs/engineering-handbook/16-volunteer-expectations.md @@ -1,17 +1,176 @@ # Volunteer Expectations -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on volunteer expectations. +COSDS is designed to welcome volunteer contributors while protecting project +quality, contributor time, and NTARI governance obligations. Volunteers are not +expected to know every system or process before participating. They are expected +to communicate clearly, work in public where appropriate, and follow repository +standards. -## Placeholder Sections +This chapter explains how volunteers can participate effectively and safely. -- Overview -- Scope -- Standards -- Responsibilities -- References +## What Volunteers Can Expect -## Status +Volunteers should expect: -Content coming soon. +- Public issues that describe available work. +- Respectful communication from maintainers and reviewers. +- Review feedback focused on the work. +- Clear contribution and security reporting paths. +- Opportunities to ask questions before taking on work. +- Recognition that availability may vary. + +Volunteers should not be expected to use private knowledge, personal accounts, +or unapproved credentials to complete public repository work. + +## What NTARI Expects from Volunteers + +| Expectation | Why it matters | +| --- | --- | +| Follow the Code of Conduct | Keeps collaboration safe and respectful. | +| Keep work scoped | Makes review possible for maintainers. | +| Communicate status | Helps coordinators avoid duplicate or stalled work. | +| Protect sensitive information | Preserves trust and security. | +| Respect licensing | Keeps AGPL-3.0 and third-party obligations intact. | +| Accept review professionally | Improves quality and shared understanding. | +| Ask questions early | Prevents wasted effort and hidden assumptions. | + +## Getting Started + +Recommended first steps: + +1. Read [Purpose](01-purpose.md) and + [Engineering Principles](02-engineering-principles.md). +2. Review [Communication Standards](04-communication-standards.md). +3. Find an issue labeled `good first issue` or `help wanted`. +4. Comment on the issue before starting substantial work. +5. Create a branch following [Branching Strategy](06-branching-strategy.md). +6. Open a pull request following [Pull Request Process](08-pull-request-process.md). + +## Choosing Work + +Good first contributions include: + +- Fixing broken links. +- Improving unclear wording. +- Adding tests for an already-defined behavior. +- Updating examples that are out of date. +- Addressing small, well-scoped bugs. + +Avoid starting with: + +- Broad rewrites. +- Security-sensitive changes without maintainer guidance. +- Major architecture changes without an RFC. +- Work that depends on private systems or credentials. + +## Communication Expectations + +Volunteers should communicate in the issue or pull request associated with the +work. + +Useful status comment: + +```markdown +I can work on this. My plan is to update the documentation example and verify +all internal links. I expect to open a pull request this weekend. +``` + +Useful blocked comment: + +```markdown +I am blocked because the expected behavior is unclear for archived projects. +Can a maintainer confirm whether archived projects should be included? +``` + +## Time and Availability + +Volunteer availability varies. Contributors should avoid taking on work they +cannot reasonably progress. + +If you need to pause work: + +- Leave a status comment. +- Explain what remains. +- Unassign yourself if the work should be available to others. +- Link any branch or draft pull request that contains useful progress. + +Maintainers may reassign stale work to keep the sprint moving. + +## Quality Expectations + +Before requesting review, volunteers should confirm: + +- The change addresses the issue or stated goal. +- The pull request is focused. +- Markdown renders correctly when documentation is changed. +- Tests or validation steps are documented. +- No secrets, private data, or unapproved third-party content are included. +- Internal links are valid. + +See [Code Review Standards](09-code-review-standards.md) for review criteria. + +## Review Participation + +Review feedback is part of collaboration. Volunteers should: + +- Ask clarifying questions when feedback is unclear. +- Respond to requested changes with updates or rationale. +- Avoid resolving conversations before the concern is addressed. +- Treat maintainers and reviewers as partners. + +Reviewers should also follow the same professional expectations. See +[Professional Conduct](17-professional-conduct.md). + +## Licensing and Attribution + +Because NTARI repositories may use AGPL-3.0, volunteers must be careful when +adding third-party material. + +Do not add: + +- Code copied from incompatible licenses. +- Images, diagrams, or text without permission or attribution. +- Generated content that cannot be reviewed or licensed appropriately. +- Dependency changes without a clear reason. + +When unsure, ask maintainers before opening the pull request. + +## Volunteer Contribution Flow + +```mermaid +flowchart TD + A[Read handbook basics] --> B[Find suitable issue] + B --> C[Comment with intent] + C --> D[Create branch] + D --> E[Make focused change] + E --> F[Open pull request] + F --> G[Respond to review] + G --> H[Merge or follow up] +``` + +## Volunteer Checklist + +Before contributing: + +- Read the repository README. +- Review contribution and conduct expectations. +- Confirm the issue is still available. +- Ask questions if scope is unclear. + +Before requesting review: + +- Link the related issue. +- Summarize the change. +- Document validation. +- Check for secrets or private information. +- Verify relevant internal links. + +## Related Chapters + +- [Purpose](01-purpose.md) +- [Engineering Roles](03-engineering-roles.md) +- [Communication Standards](04-communication-standards.md) +- [GitHub Workflow](05-github-workflow.md) +- [Professional Conduct](17-professional-conduct.md) diff --git a/docs/engineering-handbook/17-professional-conduct.md b/docs/engineering-handbook/17-professional-conduct.md index cf7e3c4..bf6b093 100644 --- a/docs/engineering-handbook/17-professional-conduct.md +++ b/docs/engineering-handbook/17-professional-conduct.md @@ -1,17 +1,164 @@ # Professional Conduct -## Purpose +## Overview -This page is reserved for future NTARI Engineering Handbook guidance on professional conduct. +Professional conduct is essential to COSDS. NTARI contributors collaborate +across backgrounds, time zones, skill levels, and roles. The goal is to create a +technical environment where people can ask questions, receive feedback, and do +high-quality work without harassment, hostility, or exclusion. -## Placeholder Sections +This chapter complements the repository +[`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md). If there is a conflict, +the Code of Conduct governs. -- Overview -- Scope -- Standards -- Responsibilities -- References +## Conduct Principles -## Status +| Principle | Practice | +| --- | --- | +| Respect people | Address the work without attacking the contributor. | +| Assume good intent, verify impact | Be generous, but correct harmful outcomes. | +| Be specific | Give actionable feedback instead of vague criticism. | +| Share context | Explain decisions for future contributors. | +| Protect inclusion | Avoid behavior that discourages participation. | +| Escalate responsibly | Raise serious concerns through appropriate channels. | -Content coming soon. +## Expected Behavior + +Expected behavior includes: + +- Using welcoming and inclusive language. +- Giving constructive feedback. +- Accepting review comments professionally. +- Asking questions without shaming others. +- Respecting boundaries and availability. +- Crediting others' work. +- Keeping disagreements focused on facts, risks, and project goals. + +## Unacceptable Behavior + +Unacceptable behavior includes: + +- Harassment or intimidation. +- Personal attacks or insults. +- Discriminatory language or exclusionary conduct. +- Publishing private information without permission. +- Retaliation against someone who reports a concern. +- Repeatedly ignoring maintainer boundaries or review decisions. +- Introducing or pressuring others to expose sensitive information. + +Report serious concerns through the process described in +[`../../CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md) or +[`../../SECURITY.md`](../../SECURITY.md), depending on the issue. + +## Feedback Standards + +Good feedback is clear, kind, and actionable. + +Good example: + +```markdown +blocking: this example includes a real-looking token. Please replace it with a +clearly fake value such as `example-token` and confirm no real credential was +used. +``` + +Poor example: + +```markdown +This is careless. Fix it. +``` + +The good example identifies the concern, explains the risk, and gives a path to +resolution. + +## Disagreement Standards + +Technical disagreement is normal. Contributors should handle disagreement by: + +1. Restating the shared goal. +2. Identifying the specific point of disagreement. +3. Separating facts from preferences. +4. Looking for reversible next steps. +5. Asking a maintainer or technical lead to decide when needed. + +Example: + +```markdown +I think we agree that the validation should happen before data is stored. The +open question is whether it belongs in the API layer or shared service layer. My +preference is the shared service layer because the CLI will need the same rule. +``` + +## Maintainer Conduct + +Maintainers have additional responsibility because they influence access, +review, and merge decisions. + +Maintainers should: + +- Apply standards consistently. +- Explain decisions when closing issues or pull requests. +- Avoid using authority to end reasonable technical discussion prematurely. +- Redirect unsafe or off-topic conversations promptly. +- Protect contributors from harassment or bad-faith participation. +- Avoid merging high-risk personal changes without independent review. + +## Volunteer Conduct + +Volunteers should: + +- Respect maintainer time and review scope. +- Avoid repeatedly requesting immediate attention. +- Keep pull requests focused. +- Accept that some proposals may be declined. +- Ask for clarification rather than guessing when work is ambiguous. +- Step back when a maintainer identifies security, license, or conduct risk. + +See [Volunteer Expectations](16-volunteer-expectations.md) for participation +guidance. + +## Inclusive Communication Checklist + +Before posting, ask: + +- Is my comment necessary and relevant? +- Is it focused on the work rather than the person? +- Does it explain what action is requested? +- Could a new contributor understand the context? +- Am I using private information that should not be public? +- Would I be comfortable with this comment representing NTARI publicly? + +## Escalation + +Escalate conduct concerns when: + +- A participant is being harassed or targeted. +- A discussion becomes hostile or unsafe. +- A contributor repeatedly ignores boundaries. +- A maintainer decision is needed to unblock work. +- Sensitive information has been exposed. + +Use public issue or pull request comments for routine technical escalation. Use +private reporting channels for conduct, security, or privacy-sensitive matters. + +## Conduct Flow + +```mermaid +flowchart TD + A[Concern arises] --> B{Routine technical issue?} + B -- Yes --> C[Discuss in issue or PR] + B -- No --> D{Sensitive or conduct risk?} + D -- Yes --> E[Use private reporting path] + D -- No --> F[Ask maintainer for guidance] + C --> G[Document decision] + F --> G + E --> H[Maintainers review safely] +``` + +## Related Chapters + +- [Communication Standards](04-communication-standards.md) +- [Volunteer Expectations](16-volunteer-expectations.md) +- [Code Review Standards](09-code-review-standards.md) +- [Engineering Roles](03-engineering-roles.md) +- [Security Standards](13-security-standards.md)