diff --git a/.editorconfig b/.editorconfig index bf8388c..e27eb6e 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,4 +1,4 @@ -# EditorConfig helps maintain consistent whitespace and formatting across contributors. +# EditorConfig keeps formatting consistent across editors. root = true [*] 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 index 2741202..b84a81c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,23 +1,27 @@ - - ## Summary -- + + +## Type of Change + +- [ ] Documentation update +- [ ] Repository configuration +- [ ] Governance or process update +- [ ] Engineering RFC +- [ ] Other maintenance -## Changes +## Related Issues or RFCs -- + -## Review Notes +## 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. -## Checklist +## Additional Notes -- [ ] I have reviewed the rendered Markdown. -- [ ] I have kept this change focused and reviewable. -- [ ] I have linked related issues, RFCs, or discussions where applicable. + 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 index d520164..d21d771 100644 --- a/.gitignore +++ b/.gitignore @@ -13,13 +13,13 @@ Thumbs.db *.tmp *.temp -# Dependency directories and build output for future documentation tooling +# Dependency directories and generic build output node_modules/ +dist/ build/ .cache/ -.docusaurus/ -# Environment files +# Local environment files .env .env.* !.env.example diff --git a/CODEOWNERS b/CODEOWNERS index ed18776..aea1150 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -6,4 +6,4 @@ /CONTRIBUTING.md @NTARI-RAND/docs-maintainers /CODE_OF_CONDUCT.md @NTARI-RAND/maintainers /SECURITY.md @NTARI-RAND/maintainers -/LICENSE @NTARI-RAND/maintainers \ No newline at end of file +/LICENSE @NTARI-RAND/maintainers diff --git a/README.md b/README.md index 1cb6a91..810c7e7 100644 --- a/README.md +++ b/README.md @@ -2,22 +2,11 @@ The NTARI Developer Portal is the official documentation repository maintained by the Network Theory Applied Research Institute (NTARI). -This repository will become the authoritative source for NTARI developer-facing documentation, including engineering guidance, architecture references, operational notes, project documentation, and contributor resources. It is currently maintained as a Markdown-first GitHub repository and may later be published with a dedicated documentation platform such as Docusaurus. +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. -## Repository Map +## Current Scope -- `docs/engineering-handbook/` — future engineering practices and standards. -- `docs/architecture/` — future architecture references and decision records. -- `docs/operations/` — future operational runbooks and support procedures. -- `docs/volunteer-guide/` — future contributor and volunteer onboarding material. -- `docs/projects/` — future project-specific documentation indexes. -- `docs/rfcs/` — future request-for-comments proposals and review records. -- `docs/assets/` — future images, diagrams, and other documentation assets. -- `templates/` — reusable Markdown templates for repository documentation. - -## Current Status - -This repository currently defines the documentation structure and the governance and contribution foundation. Handbook and operational content will be added through future pull requests. +This repository currently defines the governance and contribution foundation for the Developer Portal. Documentation pages have not been created yet. ## Maintainer