diff --git a/.bestpractices.json b/.bestpractices.json index adafd3b..7171407 100644 --- a/.bestpractices.json +++ b/.bestpractices.json @@ -233,27 +233,27 @@ "sites_password_security_status": "N/A", "sites_password_security_justification": "N/A — no user accounts or passwords. Maintainer auth handled by GitHub.", - "code_of_conduct_status": "?", - "code_of_conduct_justification": "TODO — add CODE_OF_CONDUCT.md (Contributor Covenant 2.1) at repo root.", + "code_of_conduct_status": "Met", + "code_of_conduct_justification": "Contributor Covenant 2.1 adopted. https://github.com/RandomCodeSpace/docsiq/blob/main/CODE_OF_CONDUCT.md", - "governance_status": "?", - "governance_justification": "TODO — add GOVERNANCE.md describing BDFL model with sole maintainer, PR-review decision process, and security-contact continuity plan.", + "governance_status": "Met", + "governance_justification": "Lead-maintainer model documented with decision-making process, roles, and continuity plan. https://github.com/RandomCodeSpace/docsiq/blob/main/GOVERNANCE.md", - "roles_responsibilities_status": "?", - "roles_responsibilities_justification": "TODO — document maintainer / reviewer / security-contact roles in GOVERNANCE.md.", + "roles_responsibilities_status": "Met", + "roles_responsibilities_justification": "Lead maintainer, security contact, and reviewer roles documented. https://github.com/RandomCodeSpace/docsiq/blob/main/GOVERNANCE.md#roles", - "access_continuity_status": "?", - "access_continuity_justification": "TODO — add .github/CODEOWNERS plus GOVERNANCE.md section on admin-access backup and account-recovery plan.", + "access_continuity_status": "Met", + "access_continuity_justification": ".github/CODEOWNERS routes PR review to @aksOps; GOVERNANCE.md documents admin-access continuity via reproducible builds and cosign keyless signing. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/CODEOWNERS", - "bus_factor_status": "?", - "bus_factor_justification": "TODO — note in GOVERNANCE.md that project is single-maintainer but all build/signing/registry artifacts are reproducible from source, mitigating bus-factor risk.", + "bus_factor_status": "Met", + "bus_factor_justification": "Single-maintainer risk mitigated by reproducible builds and keyless cosign signing anchored to GitHub OIDC + Rekor — not a private key. Any fork can reproduce identical release artifacts. https://github.com/RandomCodeSpace/docsiq/blob/main/GOVERNANCE.md#continuity-and-resilience", - "report_archive_status": "?", - "report_archive_justification": "TODO — confirm GitHub Issues serves as the report archive and note it in SECURITY.md.", + "report_archive_status": "Met", + "report_archive_justification": "GitHub Issues serves as the public report archive; Security Advisories archive coordinated-disclosure reports. https://github.com/RandomCodeSpace/docsiq/blob/main/SECURITY.md#report-archive", - "release_notes_vulns_status": "?", - "release_notes_vulns_justification": "TODO — add .github/release.yml template with a 'Security fixes' section auto-populated from PRs labelled `security`.", + "release_notes_vulns_status": "Met", + "release_notes_vulns_justification": ".github/release.yml defines a 'Security fixes' section auto-populated from PRs labelled `security` in GitHub-generated release notes. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/release.yml", - "accessibility_best_practices_status": "?", - "accessibility_best_practices_justification": "TODO — add docs/ACCESSIBILITY.md covering WCAG AA stance for the embedded React SPA (keyboard nav, contrast tokens, prefers-reduced-motion)." + "accessibility_best_practices_status": "Met", + "accessibility_best_practices_justification": "WCAG 2.1 Level AA stance documented for the embedded React SPA: contrast ≥ 4.5:1, keyboard nav, prefers-reduced-motion, semantic HTML, axe-core checks. https://github.com/RandomCodeSpace/docsiq/blob/main/docs/ACCESSIBILITY.md" } diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..cef6e48 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @aksOps diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..ca0363b --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,22 @@ +changelog: + categories: + - title: Security fixes + labels: + - security + - title: Breaking Changes + labels: + - breaking-change + - title: New Features + labels: + - enhancement + - feature + - title: Bug Fixes + labels: + - bug + - fix + - title: Dependencies + labels: + - dependencies + - title: Other Changes + labels: + - "*" diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b7f6d7f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,37 @@ +# Code of Conduct + +This project adopts the **[Contributor Covenant][homepage], version 2.1**. + +The full text is published at +. + +## Scope + +This Code of Conduct applies within all project spaces — the GitHub +repository, issue tracker, discussions, pull requests, and any community +channels maintained by the project — and also applies when an individual +is officially representing the project in public spaces. + +## Enforcement + +Instances of behaviour that violate this Code of Conduct may be reported +privately to the project maintainer at **ak.nitrr13@gmail.com**. + +All reports will be reviewed and investigated promptly and fairly. The +maintainer is obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement guidelines + +The project follows the Contributor Covenant's +[Community Impact Guidelines][guidelines] when determining the +consequences for any action deemed in violation of this Code of Conduct. + +[homepage]: https://www.contributor-covenant.org +[guidelines]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version +2.1, available at +. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..6787649 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,58 @@ +# Governance + +## Model + +docsiq follows a **lead-maintainer** governance model. The project currently +has one lead maintainer, **Amit Kumar** (GitHub: [@aksOps](https://github.com/aksOps), +email: ak.nitrr13@gmail.com), who holds final authority on technical direction, +release timing, security policy, and contributor access. + +The project welcomes additional co-maintainers as the community grows. Any +contributor who demonstrates sustained, high-quality involvement may be invited +to join as a co-maintainer. + +## Roles + +| Role | Who | Responsibilities | +|------|-----|-----------------| +| Lead maintainer | @aksOps | Merges PRs, cuts releases, triages issues, manages repo settings | +| Security contact | @aksOps | Receives private vulnerability reports, coordinates disclosure | +| Reviewer | Contributors invited ad-hoc | Reviews PRs; cannot merge without lead-maintainer approval | + +## Decision-making + +1. **Routine changes** (bug fixes, dependency bumps, doc improvements) — the + lead maintainer merges after CI passes. +2. **Significant changes** (new features, breaking API changes, new dependencies) — + a GitHub Discussion or PR is opened for at least 72 hours of community input + before merging. +3. **Security-sensitive changes** — handled privately via GitHub Security + Advisories; disclosed publicly after a fix ships. + +## Access continuity + +- Repository admin access is held by @aksOps. +- All build, signing, and release artifacts are fully reproducible from committed + source (`go build -tags sqlite_fts5 ./`). If maintainer access is lost, any + fork can reproduce and redistribute identical artifacts. +- `.github/CODEOWNERS` is configured so GitHub automatically requests review + from the lead maintainer on every PR. + +## Continuity and resilience + +docsiq is currently a single-maintainer project. Continuity risk is reduced by: + +- **Reproducible builds** — the full binary can be rebuilt by anyone from source. +- **Cosign keyless signing** — release signatures are anchored to the GitHub OIDC + identity and the Rekor transparency log, not a private key held by one person. +- **Open governance** — this document and all project infrastructure are + publicly committed; a new maintainer can take over without institutional + knowledge gaps. + +If the lead maintainer becomes unavailable for more than 90 days without notice, +interested contributors should open a GitHub Issue to coordinate next steps. + +## Amendments + +This document may be updated by the lead maintainer via a normal PR. Significant +governance changes will be announced in the release notes. diff --git a/SECURITY.md b/SECURITY.md index 364faad..4e34329 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -36,3 +36,11 @@ security patches. We follow coordinated disclosure. Once a fix ships in a release, we publish a [GitHub Security Advisory](https://github.com/RandomCodeSpace/docsiq/security/advisories) crediting the reporter unless they request anonymity. + +## Report archive + +Non-sensitive bug reports and their full discussion history are archived +publicly as [GitHub Issues](https://github.com/RandomCodeSpace/docsiq/issues). +Security reports are archived as +[GitHub Security Advisories](https://github.com/RandomCodeSpace/docsiq/security/advisories) +after coordinated disclosure. diff --git a/docs/ACCESSIBILITY.md b/docs/ACCESSIBILITY.md new file mode 100644 index 0000000..91e09de --- /dev/null +++ b/docs/ACCESSIBILITY.md @@ -0,0 +1,65 @@ +# Accessibility + +## Commitment + +docsiq targets **WCAG 2.1 Level AA** compliance for the embedded React SPA +served by `docsiq serve`. This document describes the current stance and +the practices enforced during development. + +## Colour and contrast + +- All text and interactive elements meet a contrast ratio of at least **4.5:1** + against their background (AA normal text) and **3:1** for large text and + UI components. +- Colour is never the sole means of conveying information (e.g. error states + use both colour and an icon or label). +- Dark mode is the default; a light theme is available. Both palettes are + tested for contrast compliance. + +## Keyboard navigation + +- All interactive elements (buttons, links, inputs, modals) are reachable and + operable via keyboard alone. +- Focus order follows the logical reading order of the page. +- Focus indicators are always visible; the default browser outline is not + suppressed without a higher-contrast replacement. +- The command palette (`Cmd/Ctrl+K`) is keyboard-first and fully navigable + without a mouse. + +## Motion + +- Non-essential animations respect `prefers-reduced-motion`. When the user + has opted out of motion, transitions are replaced with instant state changes. +- No animations trigger automatically on page load for more than 5 seconds + without a pause/stop control. + +## Screen readers + +- Semantic HTML elements are used throughout (`