diff --git a/.github/workflows/check-pr-main.yml b/.github/workflows/check-pr-main.yml index 1a041c0..ac6a09e 100644 --- a/.github/workflows/check-pr-main.yml +++ b/.github/workflows/check-pr-main.yml @@ -18,7 +18,7 @@ jobs: script: | const fs = require('fs'); const config = JSON.parse(fs.readFileSync('repos-config.json', 'utf8')); - const ALLOWED_REFS = new Set(['main', 'docs-ng']); + const ALLOWED_REFS = new Set(['main']); const errors = []; for (const repo of config.repos) { diff --git a/.github/workflows/docs-checks.yml b/.github/workflows/docs-checks.yml index 6de26df..8de3690 100644 --- a/.github/workflows/docs-checks.yml +++ b/.github/workflows/docs-checks.yml @@ -26,7 +26,7 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: - repository: gardenlinux/docs-ng + repository: gardenlinux/docs - name: Set up Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # pin@v6.2.0 @@ -66,7 +66,7 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: - repository: gardenlinux/docs-ng + repository: gardenlinux/docs - name: Download aggregated docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 @@ -102,7 +102,7 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: - repository: gardenlinux/docs-ng + repository: gardenlinux/docs - name: Download aggregated docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 @@ -137,7 +137,7 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: - repository: gardenlinux/docs-ng + repository: gardenlinux/docs - name: Download aggregated docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml index 1aacf99..e584065 100644 --- a/.github/workflows/docs-pr.yml +++ b/.github/workflows/docs-pr.yml @@ -39,9 +39,9 @@ jobs: with: client-id: ${{ secrets.DOCS_BOT_APP_ID }} private-key: ${{ secrets.DOCS_BOT_PRIVATE_KEY }} - repositories: docs-ng,${{ github.event.client_payload.repo || inputs.repo }} + repositories: docs,${{ github.event.client_payload.repo || inputs.repo }} - - name: Checkout docs-ng + - name: Checkout docs uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: token: ${{ steps.app-token.outputs.token }} diff --git a/README.md b/README.md index 8876812..f093631 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Garden Linux Documentation Framework -`docs-ng` is the primary documentation aggregation framework and hosting hub. +`docs` is the primary documentation aggregation framework and hosting hub. -The documentation is hosted at https://gardenlinux-docs.netlify.app +The documentation is hosted at https://docs.gardenlinux.org This repository contains all source code of our custom aggregation system, as well as any relevant documentation related to the topic of documenting. @@ -10,14 +10,14 @@ well as any relevant documentation related to the topic of documenting. ## Documentation To learn everything related to our approach of documenting, check the -[Documentation](https://gardenlinux-docs.netlify.app/contributing/documentation/) +[Documentation](https://docs.gardenlinux.org/contributing/documentation/) subsection of our contributing page. You can also jump directly into topics like -[how to work with the documentation system locally](https://gardenlinux-docs.netlify.app/contributing/documentation/working-locally.html), -[our documentation workflow & review process](https://gardenlinux-docs.netlify.app/contributing/documentation/documentation_workflow.html) +[how to work with the documentation system locally](https://docs.gardenlinux.org/contributing/documentation/working-locally.html), +[our documentation workflow & review process](https://docs.gardenlinux.org/contributing/documentation/documentation_workflow.html) and the -[quality markers](https://gardenlinux-docs.netlify.app/contributing/documentation/writing_good_docs.html) +[quality markers](https://docs.gardenlinux.org/contributing/documentation/writing_good_docs.html) we use to verify the quality of contributed documentation. While browsing our docs, if you find something that you would like to correct or @@ -46,7 +46,7 @@ https://lists.neonephos.org/g/gardenlinux-security-embargo We welcome your contributions to Gardenlinux or any supporting projects. To find out more, visit our -[Contributor Documentation](https://gardenlinux-docs.netlify.app/contributing). +[Contributor Documentation](https://docs.gardenlinux.org/contributing). ## Licensing diff --git a/docs/contributing/documentation/adding-repos.md b/docs/contributing/documentation/adding-repos.md index 660f3ce..251ab34 100644 --- a/docs/contributing/documentation/adding-repos.md +++ b/docs/contributing/documentation/adding-repos.md @@ -189,7 +189,7 @@ Here's a complete configuration: "name": "example-tool", "url": "https://github.com/gardenlinux/example-tool", "docs_path": "documentation", - "ref": "docs-ng", + "ref": "main", "commit": "1234567890abcdef", "root_files": ["README.md"], "structure": "flat", @@ -204,7 +204,6 @@ The `docs_path` field defaults to `"docs"` and may be omitted when the documenta ### Files Not Appearing - Verify `docs_path` points to the correct directory -- Check that the repository has a `docs-ng` branch or adjust `ref` - Ensure `github_target_path` front-matter is correct ### Media Not Copied diff --git a/docs/contributing/documentation/ci-architecture.md b/docs/contributing/documentation/ci-architecture.md index 1a5417a..2e54c37 100644 --- a/docs/contributing/documentation/ci-architecture.md +++ b/docs/contributing/documentation/ci-architecture.md @@ -1,6 +1,6 @@ --- title: "Documentation CI Architecture" -description: "How the GitHub Actions workflows across docs-ng and aggregated repositories work together to validate, preview, and publish documentation" +description: "How the GitHub Actions workflows across docs and aggregated repositories work together to validate, preview, and publish documentation" order: 6 related_topics: - /contributing/documentation/documentation_workflow.md @@ -26,7 +26,7 @@ The documentation CI pipeline serves three guarantees: it can influence the published site. 2. **Preview**: contributors and reviewers can inspect exactly how a pull request's documentation changes will look on the live site, via a Netlify - deploy preview attached to an automated draft PR in `docs-ng`. + deploy preview attached to an automated draft PR in `docs`. 3. **Always latest docs**: once a PR of an aggregated repository (source PR) is merged, the `repos-config.json` commit lock for that repository is automatically updated so the published site reflects the latest content without any manual intervention. @@ -37,17 +37,17 @@ for the per-workflow details. ## Actors and Repositories -### [`gardenlinux/docs-ng`](https://github.com/gardenlinux/docs-ng) +### [`gardenlinux/docs`](https://github.com/gardenlinux/docs) The central aggregation hub. It hosts: -- The reusable quality-checks workflow ([`docs-checks.yml`](https://github.com/gardenlinux/docs-ng/blob/main/.github/workflows/docs-checks.yml)), which can be +- The reusable quality-checks workflow ([`docs-checks.yml`](https://github.com/gardenlinux/docs/blob/main/.github/workflows/docs-checks.yml)), which can be called from any aggregated repo. -- The automated PR workflow ([`docs-pr.yml`](https://github.com/gardenlinux/docs-ng/blob/main/.github/workflows/docs-pr.yml)), which creates and maintains draft - PRs in `docs-ng` when aggregated repos signal a documentation change. -- The config validator workflow ([`check-pr-main.yml`](https://github.com/gardenlinux/docs-ng/blob/main/.github/workflows/check-pr-main.yml)), which guards `main` - against non-production refs in [`repos-config.json`](https://github.com/gardenlinux/docs-ng/blob/main/repos-config.json). -- The [`repos-config.json`](https://github.com/gardenlinux/docs-ng/blob/main/repos-config.json) file that records which repo and which exact commit +- The automated PR workflow ([`docs-pr.yml`](https://github.com/gardenlinux/docs/blob/main/.github/workflows/docs-pr.yml)), which creates and maintains draft + PRs in `docs` when aggregated repos signal a documentation change. +- The config validator workflow ([`check-pr-main.yml`](https://github.com/gardenlinux/docs/blob/main/.github/workflows/check-pr-main.yml)), which guards `main` + against non-production refs in [`repos-config.json`](https://github.com/gardenlinux/docs/blob/main/repos-config.json). +- The [`repos-config.json`](https://github.com/gardenlinux/docs/blob/main/repos-config.json) file that records which repo and which exact commit is currently published. ### Aggregated repositories @@ -55,15 +55,15 @@ The central aggregation hub. It hosts: Each repository listed in `repos-config.json` contains `docs-check.yml` workflow that: - reacts to pull request and push events on documentation-relevant paths, -- calls the reusable `docs-checks.yml` from `docs-ng`, passing the PR's +- calls the reusable `docs-checks.yml` from `docs`, passing the PR's branch and commit as override inputs, and - on success (or on merge), dispatches a `repository_dispatch` event to - `docs-ng` to trigger the automated PR workflow. + `docs` to trigger the automated PR workflow. ### `gardenlinux-docs-bot` GitHub App -A GitHub App with write access to both `docs-ng` and the aggregated repositories. -It's responsible for generating short-lived tokens that allow cross-repository API calls without using a personal access token, opening and updating draft PRs in `docs-ng` and posting comments back to the PRs in the aggregated repo which include links to the Netlify preview. +A GitHub App with write access to both `docs` and the aggregated repositories. +It's responsible for generating short-lived tokens that allow cross-repository API calls without using a personal access token, opening and updating draft PRs in `docs` and posting comments back to the PRs in the aggregated repo which include links to the Netlify preview. Required secrets (configured in each aggregated repository): @@ -74,15 +74,15 @@ Required secrets (configured in each aggregated repository): ### Netlify -`docs-ng` has a [Netlify](https://www.netlify.com/) integration that automatically creates a deploy preview +`docs` has a [Netlify](https://www.netlify.com/) integration that automatically creates a deploy preview for every open PR. The `docs-pr.yml` workflow posts the preview URL as a comment on the originating aggregated repo PR so reviewers do not have to navigate -to `docs-ng` manually. +to `docs` manually. ## Build Flow The diagram below shows the path from a documentation change in an aggregated -repository through to a merged commit lock update in `docs-ng`. +repository through to a merged commit lock update in `docs`. ```mermaid flowchart TD @@ -90,23 +90,23 @@ flowchart TD subgraph source["Aggregated Repo (e.g. gardenlinux)"] B["docs-check.yml\ntriggered by PR event\non docs/** paths"] - B --> C["calls reusable workflow\ndocs-checks.yml @ docs-ng\nwith override-repo, override-ref,\noverride-commit"] + B --> C["calls reusable workflow\ndocs-checks.yml @ docs\nwith override-repo, override-ref,\noverride-commit"] end - subgraph docsng["gardenlinux/docs-ng"] + subgraph docsng["gardenlinux/docs"] C --> D["docs-checks.yml\nJob: aggregate\n(runs aggregate.py with overrides)"] D --> E["Job: linkcheck\n(lychee)"] D --> F["Job: spelling\n(codespell via make spelling)"] D --> G["Job: woke\n(inclusive language)"] end - E & F & G -->|all pass| H["notify-docs-ng job\nin aggregated repo"] + E & F & G -->|all pass| H["notify-docs job\nin aggregated repo"] H -->|repository_dispatch\nevent: docs-pr| I - subgraph docsng2["gardenlinux/docs-ng"] + subgraph docsng2["gardenlinux/docs"] I["docs-pr.yml\ncreates or updates branch\nauto//"] I --> J["Updates repos-config.json\ncommit lock"] - J --> K["git push -f\nOpens / updates draft PR\nin docs-ng"] + J --> K["git push -f\nOpens / updates draft PR\nin docs"] K --> L["Posts preview comment\non source repo PR"] K --> M["check-pr-main.yml\nvalidates repos-config.json\nref must be main or semver"] K --> N["Netlify deploy preview\nbuilt from draft PR branch"] @@ -117,8 +117,8 @@ flowchart TD O --> P{Source PR merged?} P -->|yes| Q["docs-check.yml\nclosed+merged event\nskips quality checks\ndispatches event=merged"] - Q --> R["docs-pr.yml\nupdates lock to merge commit\nsets ref to base branch\nun-drafts PR in docs-ng"] - R --> S[Maintainer merges\ndocs-ng PR] + Q --> R["docs-pr.yml\nupdates lock to merge commit\nsets ref to base branch\nun-drafts PR in docs"] + R --> S[Maintainer merges\ndocs PR] S --> T[Published site updated] P -->|no, more commits| A @@ -144,7 +144,7 @@ sequenceDiagram autonumber actor Dev as Developer participant SrcRepo as Aggregated Repo
(e.g. gardenlinux) - participant DocsNG as gardenlinux/docs-ng + participant DocsNG as gardenlinux/docs participant Bot as gardenlinux-docs-bot participant Netlify @@ -156,14 +156,14 @@ sequenceDiagram DocsNG->>DocsNG: spelling job (codespell) DocsNG->>DocsNG: woke job (inclusive language) DocsNG-->>SrcRepo: all checks pass ✓ - SrcRepo->>SrcRepo: notify-docs-ng job runs - SrcRepo->>Bot: create GitHub App token
(repos: docs-ng, aggregated repo) + SrcRepo->>SrcRepo: notify-docs job runs + SrcRepo->>Bot: create GitHub App token
(repos: docs, aggregated repo) SrcRepo->>DocsNG: repository_dispatch
event_type: docs-pr
payload: {repo, pr_number, commit_sha, ref, event: pr_success} DocsNG->>DocsNG: docs-pr.yml triggered DocsNG->>DocsNG: create/update branch
auto// DocsNG->>DocsNG: update repos-config.json
commit lock → override-commit DocsNG->>DocsNG: git push -f to branch - DocsNG->>DocsNG: open/update draft PR in docs-ng
(status: Draft) + DocsNG->>DocsNG: open/update draft PR in docs
(status: Draft) DocsNG->>DocsNG: check-pr-main.yml validates
repos-config.json refs Netlify->>Netlify: build deploy preview
from draft PR branch Bot->>SrcRepo: post/update comment on source PR
📚 Preview PR link
😎 Netlify deploy preview URL @@ -174,19 +174,19 @@ sequenceDiagram When the source PR is merged, `docs-check.yml` fires again with `action: closed` and `merged: true`. The quality checks are skipped; only the -notification job runs to promote the draft docs-ng PR to ready-for-review. +notification job runs to promote the draft docs PR to ready-for-review. ```mermaid sequenceDiagram autonumber actor Maint as Maintainer participant SrcRepo as Aggregated Repo - participant DocsNG as gardenlinux/docs-ng + participant DocsNG as gardenlinux/docs participant Bot as gardenlinux-docs-bot Maint->>SrcRepo: merge PR into main SrcRepo->>SrcRepo: docs-check.yml triggered
(PR closed + merged = true)
docs-checks job SKIPPED - SrcRepo->>SrcRepo: notify-docs-ng job runs
(always, merged condition) + SrcRepo->>SrcRepo: notify-docs job runs
(always, merged condition) SrcRepo->>Bot: create GitHub App token SrcRepo->>DocsNG: repository_dispatch
event_type: docs-pr
payload: {repo, pr_number,
commit_sha: merge_commit_sha,
ref: base_branch,
event: merged} DocsNG->>DocsNG: docs-pr.yml triggered @@ -195,7 +195,7 @@ sequenceDiagram DocsNG->>DocsNG: git push -f to branch DocsNG->>DocsNG: update existing PR:
draft: false (ready for review)
status: "Ready for review" Bot->>SrcRepo: update comment on source PR
with current status - Maint->>DocsNG: review and merge docs-ng PR + Maint->>DocsNG: review and merge docs PR DocsNG->>DocsNG: published site updated
(next aggregation run picks up new lock) ``` @@ -207,9 +207,9 @@ be visible. ### Quality checks fail in the aggregated repo If any of the `linkcheck`, `spelling`, or `woke` jobs in `docs-checks.yml` -fail, the `notify-docs-ng` job in `docs-check.yml` does **not** run (the +fail, the `notify-docs` job in `docs-check.yml` does **not** run (the `needs: [docs-checks]` condition `result == 'success'` is not met). No -dispatch event is sent to `docs-ng`, and no draft PR is created or updated. +dispatch event is sent to `docs`, and no draft PR is created or updated. The failure is visible as a failed status check directly on the aggregated repo PR. @@ -223,11 +223,11 @@ If the `docs-pr.yml` workflow fails (e.g., because the GitHub App token cannot be obtained, or because the `repos-config.json` entry for the aggregated repo does not exist), no draft PR is opened and no comment is posted. -Check the `docs-pr.yml` run in the **Actions** tab of `docs-ng` for the error. +Check the `docs-pr.yml` run in the **Actions** tab of `docs` for the error. -### `check-pr-main.yml` blocks the docs-ng PR +### `check-pr-main.yml` blocks the docs PR -If the docs-ng draft PR's `repos-config.json` still contains a non-`main`, +If the docs draft PR's `repos-config.json` still contains a non-`main`, non-semver `ref` when someone tries to merge it to `main`, `check-pr-main.yml` will fail and prevent the merge. This happens if the source PR was never merged (the draft PR still points at a feature branch ref). @@ -235,7 +235,7 @@ merged (the draft PR still points at a feature branch ref). The fix is to either wait for the source PR to be merged (which will update the ref to `main`) or to close the draft PR if the source PR was abandoned. - + ![non-main ref check failed](../assets/check-pr-main-fail.png) ### Netlify preview not available @@ -257,10 +257,10 @@ details. |---------|--------------| | aggregatated-repo (source) PR missing docs status check | **Actions** tab of the aggregated repo → `Documentation Quality Check` run | | Quality check job details (which lint rule failed) | Expand the failing job step in the aggregated repo Actions run | -| No comment on source PR with preview link | **Actions** tab of `docs-ng` → `Create/Update Docs PR` run; check the `Comment on source PR` step | -| Draft PR in `docs-ng` not created | **Actions** tab of `docs-ng` → `Create/Update Docs PR` run; check `Create or update branch` and `Create or update PR` steps | -| `repos-config.json` ref validation fails | **Checks** tab on the draft PR in `docs-ng` → `Validate repos-config.json` run | -| Netlify preview not building | Netlify dashboard → deploy log for the docs-ng PR branch | +| No comment on source PR with preview link | **Actions** tab of `docs` → `Create/Update Docs PR` run; check the `Comment on source PR` step | +| Draft PR in `docs` not created | **Actions** tab of `docs` → `Create/Update Docs PR` run; check `Create or update branch` and `Create or update PR` steps | +| `repos-config.json` ref validation fails | **Checks** tab on the draft PR in `docs` → `Validate repos-config.json` run | +| Netlify preview not building | Netlify dashboard → deploy log for the docs PR branch | | Bot cannot authenticate | Verify `DOCS_BOT_APP_ID` and `DOCS_BOT_PRIVATE_KEY` secrets are set in the aggregated repository's settings | ## Related Topics diff --git a/docs/contributing/documentation/ci-workflows-reference.md b/docs/contributing/documentation/ci-workflows-reference.md index 599ec37..5001217 100644 --- a/docs/contributing/documentation/ci-workflows-reference.md +++ b/docs/contributing/documentation/ci-workflows-reference.md @@ -23,14 +23,14 @@ related_topics: | ------------ | ----------------------------------------------------------------------- | | **File** | `.github/workflows/docs-check.yml` | | **Lives in** | Each aggregated repository | -| **Type** | Caller workflow — invokes the reusable `docs-checks.yml` from `docs-ng` | +| **Type** | Caller workflow — invokes the reusable `docs-checks.yml` from `docs` | ### Triggers ```yaml on: pull_request: - branches: [main, docs-ng] + branches: [main] types: [opened, synchronize, reopened, closed] paths: - "docs/**" @@ -40,7 +40,7 @@ on: - "CONTRIBUTING.md" - "SECURITY.md" push: - branches: [main, docs-ng] + branches: [main] paths: # (same path list as above) ``` @@ -53,8 +53,8 @@ can detect merged PRs. | Job | Condition | Purpose | | ---------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `docs-checks` | Skipped when `action == 'closed'` | Calls the reusable quality-check workflow in `docs-ng` with override inputs | -| `notify-docs-ng` | Runs after `docs-checks` succeeds **or** when a PR is merged (always-conditional) | Generates a GitHub App token and sends a `repository_dispatch` to `docs-ng` | +| `docs-checks` | Skipped when `action == 'closed'` | Calls the reusable quality-check workflow in `docs` with override inputs | +| `notify-docs` | Runs after `docs-checks` succeeds **or** when a PR is merged (always-conditional) | Generates a GitHub App token and sends a `repository_dispatch` to `docs` | ### Inputs Passed to Reusable Workflow @@ -64,7 +64,7 @@ can detect merged PRs. | `override-ref` | `github.head_ref` (PR branch) or `github.ref_name` (push) | | `override-commit` | `pull_request.head.sha` or `github.sha` | -### Dispatch Payload Sent to `docs-ng` +### Dispatch Payload Sent to `docs` ```json { @@ -86,7 +86,7 @@ can detect merged PRs. ### Outputs / Side-Effects - On open/synchronize PR: calls reusable workflow → on success dispatches - `docs-pr` event to `docs-ng`. + `docs-pr` event to `docs`. - On merged PR: skips quality checks, dispatches `docs-pr` event with `event: merged` and `ref` set to the base branch. @@ -95,11 +95,11 @@ can detect merged PRs. ```mermaid flowchart TD A["PR event on docs paths"] --> B{action == closed?} - B -->|no| C["docs-checks job
(calls docs-checks.yml @ docs-ng)"] - C -->|success| D["notify-docs-ng job"] + B -->|no| C["docs-checks job
(calls docs-checks.yml @ docs)"] + C -->|success| D["notify-docs job"] B -->|yes, merged| D B -->|yes, not merged| E["workflow ends
(no action)"] - D --> F["repository_dispatch → docs-ng
event_type: docs-pr"] + D --> F["repository_dispatch → docs
event_type: docs-pr"] class A input class C,D process @@ -113,7 +113,7 @@ flowchart TD | Symptom | Likely cause | | -------------------------- | -------------------------------------------------------------------------------------------------- | | `docs-checks` job fails | Broken links, spelling errors, or woke violations in the documentation change | -| `notify-docs-ng` job fails | `DOCS_BOT_APP_ID` or `DOCS_BOT_PRIVATE_KEY` secret missing/invalid; App not installed on `docs-ng` | +| `notify-docs` job fails | `DOCS_BOT_APP_ID` or `DOCS_BOT_PRIVATE_KEY` secret missing/invalid; App not installed on `docs` | | Workflow not triggered | Changed files do not match the `paths:` filter | ## 2. `docs-checks.yml` — Reusable Quality Checks Workflow @@ -121,7 +121,7 @@ flowchart TD | | | | ------------ | --------------------------------------------------------- | | **File** | `.github/workflows/docs-checks.yml` | -| **Lives in** | `gardenlinux/docs-ng` | +| **Lives in** | `gardenlinux/docs` | | **Type** | Reusable workflow (`workflow_call`) + own PR/push trigger | ### Triggers @@ -149,7 +149,7 @@ on: ``` When called via `workflow_call`, it validates external repo documentation. -When triggered directly by PR/push in `docs-ng`, it validates the aggregator's +When triggered directly by PR/push in `docs`, it validates the aggregator's own documentation (with no overrides — all repos use their pinned commits). ### Inputs @@ -222,7 +222,7 @@ flowchart TD | | | | ------------ | ------------------------------------------------------------- | | **File** | `.github/workflows/docs-pr.yml` | -| **Lives in** | `gardenlinux/docs-ng` | +| **Lives in** | `gardenlinux/docs` | | **Type** | `repository_dispatch` consumer + `workflow_dispatch` (manual) | ### Triggers @@ -265,8 +265,8 @@ The `client_payload` (or `inputs` for manual dispatch) must contain: ### Job Steps (in order) 1. **Generate GitHub App token** — creates a token with write access to - `docs-ng` and the source repository. -2. **Checkout docs-ng** — full fetch depth for branch operations. + `docs` and the source repository. +2. **Checkout docs** — full fetch depth for branch operations. 3. **Configure git** — sets bot identity for commits. 4. **Extract payload** — normalizes `repository_dispatch` and `workflow_dispatch` inputs into step outputs. @@ -278,24 +278,24 @@ The `client_payload` (or `inputs` for manual dispatch) must contain: `main`). 8. **Create or update PR** — opens a draft PR (for `pr_success`) or marks an existing PR as ready-for-review (for `merged`). -9. **Comment on source PR** — posts or updates a comment with the docs-ng +9. **Comment on source PR** — posts or updates a comment with the docs PR link and Netlify deploy preview URL. ### Required Secrets | Secret | Purpose | | ---------------------- | ------------------------------------------------------------ | -| `DOCS_BOT_APP_ID` | GitHub App identifier (configured at org level in `docs-ng`) | +| `DOCS_BOT_APP_ID` | GitHub App identifier (configured at org level in `docs`) | | `DOCS_BOT_PRIVATE_KEY` | Private key for JWT token generation | ### Outputs / Side-Effects | Side-effect | Details | | ----------------------------------- | ------------------------------------------------------ | -| Branch `auto//` | Created or force-updated in `docs-ng` | -| Draft PR in `docs-ng` | Title: `docs(): Update commit lock from PR #` | +| Branch `auto//` | Created or force-updated in `docs` | +| Draft PR in `docs` | Title: `docs(): Update commit lock from PR #` | | PR transitioned to ready-for-review | When `event == merged` | -| Comment on source PR | Contains docs-ng PR URL and Netlify preview link | +| Comment on source PR | Contains docs PR URL and Netlify preview link | ### Branch Naming Convention @@ -312,7 +312,7 @@ Examples: `auto/gardenlinux/4521`, `auto/builder/87`. ```mermaid flowchart TD A["repository_dispatch
event_type: docs-pr"] --> B["Generate GitHub App token"] - B --> C["Checkout docs-ng
(full history)"] + B --> C["Checkout docs
(full history)"] C --> D["Extract payload fields"] D --> E["Create/update branch
auto//"] E --> F["Update repos-config.json
(commit + ref)"] @@ -332,9 +332,8 @@ flowchart TD | Symptom | Likely cause | | ------------------------------------------- | --------------------------------------------------------------------------------------------- | -| Job fails at "Generate GitHub App token" | `DOCS_BOT_APP_ID` or `DOCS_BOT_PRIVATE_KEY` not set in `docs-ng` repository secrets | +| Job fails at "Generate GitHub App token" | `DOCS_BOT_APP_ID` or `DOCS_BOT_PRIVATE_KEY` not set in `docs` repository secrets | | "Repository not found in repos-config.json" | The dispatching repo's name does not match any `name` field in `repos-config.json` | -| Force-push fails | Branch protection rules on `docs-ng` blocking the bot (auto branches should not be protected) | | Comment not posted | App token lacks write access to the source repo's issues/PRs | ## 4. `check-pr-main.yml` — `repos-config.json` Validator @@ -342,7 +341,7 @@ flowchart TD | | | | ------------ | ------------------------------------- | | **File** | `.github/workflows/check-pr-main.yml` | -| **Lives in** | `gardenlinux/docs-ng` | +| **Lives in** | `gardenlinux/docs` | | **Type** | PR validator (status check) | ### Triggers @@ -353,13 +352,13 @@ on: branches: [main] ``` -Runs on every PR targeting `main` in `docs-ng`. There is no path filter — it +Runs on every PR targeting `main` in `docs`. There is no path filter — it always runs because `repos-config.json` could be modified in any PR. ### Purpose Prevents merging a PR that contains non-production references in -`repos-config.json`. This ensures that once a docs-ng PR is merged, the site +`repos-config.json`. This ensures that once a docs PR is merged, the site builds against stable refs only. ### Validation Rules @@ -368,7 +367,6 @@ The workflow checks every entry in `repos-config.json.repos[]` and fails if any `ref` value is **not** one of: - `main` -- `docs-ng` - A semantic version string matching `^\d+\.\d+\.\d+$` If a ref points to a feature branch (e.g., `feature/my-docs-change`), the @@ -398,7 +396,7 @@ None. The workflow only reads the repository contents using the default flowchart TD A["PR opened/updated
targeting main"] --> B["Checkout PR branch"] B --> C["Read repos-config.json"] - C --> D{"For each repo:
ref ∈ {main, docs-ng, semver}?"} + C --> D{"For each repo:
ref ∈ {main, semver}?"} D -->|all valid| E["✓ Check passes"] D -->|invalid refs found| F["✗ Check fails
lists non-compliant repos"] @@ -415,7 +413,6 @@ flowchart TD | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Check fails with "non-main branch references" | The automated PR was created from an open (not yet merged) source PR — the ref still points at the feature branch | | Check fails after source PR was merged | Race condition — the `docs-pr.yml` workflow has not yet run to update the ref. Wait for the "merged" dispatch to complete and force-push the updated branch | -| False positive on `docs-ng` ref | The `docs-ng` ref is in the allowed set — if validation fails, check the exact spelling in `repos-config.json` | ## Related Topics diff --git a/docs/contributing/documentation/configuration.md b/docs/contributing/documentation/configuration.md index 1cff615..b72bad2 100644 --- a/docs/contributing/documentation/configuration.md +++ b/docs/contributing/documentation/configuration.md @@ -86,7 +86,7 @@ git operations. - **Type:** String - **Description:** Git reference to fetch (branch, tag, or commit) -- **Examples:** `"main"`, `"docs-ng"`, `"v1.0.0"` +- **Examples:** `"main"`, `"v1.0.0"` - **Notes:** Required for git URLs; ignored for `file://` URLs ### Optional Fields @@ -137,20 +137,20 @@ git operations. { "name": "gardenlinux", "url": "https://github.com/gardenlinux/gardenlinux", - "ref": "docs-ng", + "ref": "main", "commit": "c4b1d8d7f878fcb3e779315d28e35fcb19ae4dfb", "root_files": ["CONTRIBUTING.md", "SECURITY.md"] }, { "name": "builder", "url": "https://github.com/gardenlinux/builder", - "ref": "docs-ng", + "ref": "main", "commit": "b10476ad8c46130f310e36daa42c6e2c14fb51a9" }, { "name": "python-gardenlinux-lib", "url": "https://github.com/gardenlinux/python-gardenlinux-lib", - "ref": "docs-ng", + "ref": "main", "commit": "9142fccc3d83ab51759db7d328fa19166bc1df63", "structure": "sphinx", "target_map": { @@ -168,7 +168,7 @@ git operations. - Use HTTPS git URLs - Include `commit` locks for reproducibility -- Use `docs-ng` or stable branches for `ref` +- Use stable branches for `ref` ### Development (`repos-config.local.json`) @@ -234,7 +234,7 @@ github_target_path: "docs/tutorials/my-tutorial.md" When using `github_target_path` for aggregated content, you can include additional metadata: - **`github_org`**: Organization name (e.g., `"gardenlinux"`) -- **`github_repo`**: Repository name (e.g., `"docs-ng"`) +- **`github_repo`**: Repository name (e.g., `"gardenlinux"`) - **`github_source_path`**: Original file path in source repo (e.g., `"docs/tutorial.md"`) - **`github_branch`**: Branch name for edit links (default: `"main"`) diff --git a/docs/contributing/documentation/testing.md b/docs/contributing/documentation/testing.md index 93273c5..0605787 100644 --- a/docs/contributing/documentation/testing.md +++ b/docs/contributing/documentation/testing.md @@ -183,7 +183,7 @@ Target coverage levels: Tests run automatically on: - Pull requests -- Pushes to main/docs-ng branches +- Pushes to main branch - Scheduled nightly builds ## Debugging Tests diff --git a/docs/contributing/documentation/working-locally.md b/docs/contributing/documentation/working-locally.md index 76ee793..50e0b4c 100644 --- a/docs/contributing/documentation/working-locally.md +++ b/docs/contributing/documentation/working-locally.md @@ -18,7 +18,7 @@ related_topics: # Contributing to the Garden Linux Documentation Garden Linux documentation is published at -**https://gardenlinux-docs.netlify.app/** and combines content from multiple +**https://docs.gardenlinux.org/** and combines content from multiple repositories into a unified documentation site. ## Working with the Documentation System Locally @@ -36,8 +36,8 @@ documentation system locally. ### Step 1: Clone the Repository ```bash -git clone https://github.com/gardenlinux/docs-ng.git -cd docs-ng +git clone https://github.com/gardenlinux/docs.git +cd docs ``` ### Step 2: Install Dependencies diff --git a/docs/how-to/reporting-issues.md b/docs/how-to/reporting-issues.md index 64daf63..1c404fa 100644 --- a/docs/how-to/reporting-issues.md +++ b/docs/how-to/reporting-issues.md @@ -47,4 +47,4 @@ and analyze the issue._ ## Documentation Issue? -Did you find something to improve in this documentation? [Open a new issue](https://github.com/gardenlinux/docs-ng/issues/new/choose). +Did you find something to improve in this documentation? [Open a new issue](https://github.com/gardenlinux/docs/issues/new/choose). diff --git a/lychee.toml b/lychee.toml index f601600..3e70d2b 100644 --- a/lychee.toml +++ b/lychee.toml @@ -24,8 +24,8 @@ exclude = [ "^https://github\\.com/gardenlinux/builder/blob/main/reference/features$", "^https://github\\.com/gardenlinux/gardenlinux/tree/main/tests/platformSetup/", "^https://github\\.com/gardenlinux/python-gardenlinux-lib/blob/main/_static/", - "^https://github\\.com/gardenlinux/docs-ng/blob/main/src/README\\.md$", - "^https://github\\.com/gardenlinux/docs-ng/blob/main/tests/README\\.md$", + "^https://github\\.com/gardenlinux/docs/blob/main/src/README\\.md$", + "^https://github\\.com/gardenlinux/docs/blob/main/tests/README\\.md$", "^http://packages\\.gardenlinux\\.io/gardenlinux$", ] diff --git a/src/aggregate.py b/src/aggregate.py index a7f27ab..a0b0baf 100755 --- a/src/aggregate.py +++ b/src/aggregate.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """ -Unified documentation aggregation script for docs-ng +Unified documentation aggregation script for docs This script orchestrates documentation aggregation from multiple repositories. All heavy lifting is done by the aggregation package modules. diff --git a/src/aggregation/__init__.py b/src/aggregation/__init__.py index 9f765c6..fc72613 100644 --- a/src/aggregation/__init__.py +++ b/src/aggregation/__init__.py @@ -1,4 +1,4 @@ -"""Aggregation package for docs-ng documentation aggregation.""" +"""Aggregation package for docs documentation aggregation.""" # Re-export commonly used functions for backward compatibility with tests from .config import load_config, save_config diff --git a/src/aggregation/fetcher.py b/src/aggregation/fetcher.py index ccf2568..cacf2a3 100644 --- a/src/aggregation/fetcher.py +++ b/src/aggregation/fetcher.py @@ -36,7 +36,7 @@ def __init__(self, project_root: Path, update_locks: bool = False): Initialize fetcher. Args: - project_root: Root directory of docs-ng project + project_root: Root directory of docs project update_locks: Whether we're in update-locks mode (allows commit mismatches) """ self.project_root = project_root diff --git a/src/aggregation/github_api.py b/src/aggregation/github_api.py index 47e499a..0a30e22 100644 --- a/src/aggregation/github_api.py +++ b/src/aggregation/github_api.py @@ -1,6 +1,6 @@ -"""GitHub API HTTP client for docs-ng aggregation. +"""GitHub API HTTP client for docs aggregation. -This module is the single entry point for all GitHub HTTP calls in docs-ng. +This module is the single entry point for all GitHub HTTP calls in docs. Future callers should use :func:`get_json` or :func:`list_repo_releases` rather than writing ad-hoc HTTP requests. @@ -51,7 +51,7 @@ def _build_request(url: str) -> urllib.request.Request: headers = { "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28", - "User-Agent": "gardenlinux-docs-ng", + "User-Agent": "gardenlinux-docs", } token = os.environ.get("GITHUB_TOKEN", "").strip() diff --git a/src/aggregation/sphinx_builder.py b/src/aggregation/sphinx_builder.py index f82e969..cea3260 100644 --- a/src/aggregation/sphinx_builder.py +++ b/src/aggregation/sphinx_builder.py @@ -143,7 +143,7 @@ def build_sphinx_markdown( # Step 3: Copy hand-written Markdown files from the raw docs source # that carry a ``github_target_path`` frontmatter field. These are - # manually authored docs-ng pages (how-to guides, overviews, etc.) that + # manually authored docs pages (how-to guides, overviews, etc.) that # live alongside the RST source in the repo. The sphinx builder only # produces output from RST sources, so these files would be silently # dropped without this step. @@ -172,7 +172,7 @@ def _copy_manual_markdown( ``github_target_path:`` frontmatter field and whose target path is **not** already covered by a sphinx-built file in *target_map*. - These files are manually authored docs-ng pages (how-to guides, overview + These files are manually authored docs pages (how-to guides, overview pages, etc.) that live alongside the RST sources in the repository. The sphinx builder ignores them because they are not RST, so without this step they would be silently dropped when the sphinx builder takes over the full diff --git a/tests/integration/test_aggregation.py b/tests/integration/test_aggregation.py index ef86440..a99e98b 100644 --- a/tests/integration/test_aggregation.py +++ b/tests/integration/test_aggregation.py @@ -120,7 +120,7 @@ def test_fetch_local_with_root_files_glob(self, tmp_path): def test_fetch_local_resolves_relative_path(self, tmp_path): """Test that a relative file:// URL is resolved against project_root.""" # Simulate a sibling-directory layout: project_root and mock-repo are siblings - project_root = tmp_path / "docs-ng" + project_root = tmp_path / "docs" project_root.mkdir() repo_path = tmp_path / "mock-repo" @@ -193,4 +193,4 @@ def test_process_markdown_with_frontmatter(self, tmp_path): # Verify frontmatter was fixed content = (target_dir / "test.md").read_text() assert '"Test: Example"' in content # Colon should be quoted - assert '"tag1, tag2"' in content # Comma should be quoted \ No newline at end of file + assert '"tag1, tag2"' in content # Comma should be quoted