From f625ee9d2efcd039c66285b11b945915e08f02f7 Mon Sep 17 00:00:00 2001 From: miroslavpojer Date: Thu, 3 Sep 2026 10:41:27 +0200 Subject: [PATCH 1/2] fix(tutorials): update Python version and output file names in tutorials --- docs/guides/getting-started.md | 8 ++++---- docs/introduction/quickstart.md | 6 +++--- docs/tutorials/ado-workitems-to-markdown.md | 6 +++--- docs/tutorials/gh-issues-to-markdown.md | 6 +++--- docs/tutorials/gh-source-to-markdown.md | 6 +++--- docs/tutorials/gh-source-to-pdf.md | 6 +++--- docs/tutorials/user-stories-to-pdf.md | 6 +++--- 7 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 0967b0e..1c26e80 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -52,17 +52,17 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: '3.10' - name: Normalize (toolkit) run: | pip install living-doc-toolkit - living-doc normalize-issues --input doc-issues.json --output pdf_ready.json # renamed to generator-ready.json in a coming release + living-doc normalize-issues --input doc-issues.json --output generator-ready.json - name: Generate Markdown uses: AbsaOSS/living-doc-generator-markdown@v1 with: - source-path: pdf_ready.json + source-path: generator-ready.json output-path: docs/generated - name: Publish @@ -76,7 +76,7 @@ jobs: A few things to note about these inputs: -- `doc-issues.json` / `pdf_ready.json` are `collector-gh`'s and `toolkit`'s current documented file names (`pdf_ready.json` is slated to be renamed `generator-ready.json` — see [Data Flows & Schemas](../specs/data-flows.md) §5 — but that migration hasn't shipped yet, so use `pdf_ready.json` today). +- `doc-issues.json` and `generator-ready.json` are `collector-gh`'s and `toolkit`'s documented file names — `generator-ready.json` is the canonical dataset `toolkit`'s `normalize-issues` step emits (see [Data Flows & Schemas](../specs/data-flows.md) §5 for the naming rationale). - `living-doc normalize-issues` is `toolkit`'s actual CLI command, taking `--input`/`--output` file paths — this is a workflow step like any other, not a local-only affordance. - Swap the collector/generator `uses:` steps for the ones you picked in steps 1–2 above; each project's own README documents its exact action inputs and outputs, which evolve faster than this guide. diff --git a/docs/introduction/quickstart.md b/docs/introduction/quickstart.md index bd3bad5..14c0dc7 100644 --- a/docs/introduction/quickstart.md +++ b/docs/introduction/quickstart.md @@ -80,17 +80,17 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: '3.10' - name: Normalize (toolkit) run: | pip install living-doc-toolkit - living-doc normalize-issues --input doc-issues.json --output pdf_ready.json # renamed to generator-ready.json in a coming release + living-doc normalize-issues --input doc-issues.json --output generator-ready.json # 3. GENERATE — canonical dataset -> Markdown files - name: Generate Markdown uses: AbsaOSS/living-doc-generator-markdown@v1 with: - source-path: pdf_ready.json + source-path: generator-ready.json output-path: docs/generated # 4. COMMIT the refreshed docs diff --git a/docs/tutorials/ado-workitems-to-markdown.md b/docs/tutorials/ado-workitems-to-markdown.md index 3dd68a1..db8f5f7 100644 --- a/docs/tutorials/ado-workitems-to-markdown.md +++ b/docs/tutorials/ado-workitems-to-markdown.md @@ -38,16 +38,16 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: '3.10' - name: Normalize (toolkit) run: | pip install living-doc-toolkit - living-doc normalize-issues --input work-items.json --output pdf_ready.json # renamed to generator-ready.json in a coming release + living-doc normalize-issues --input work-items.json --output generator-ready.json - name: Generate Markdown uses: AbsaOSS/living-doc-generator-markdown@v1 with: - source-path: pdf_ready.json + source-path: generator-ready.json output-path: docs/generated - name: Commit output diff --git a/docs/tutorials/gh-issues-to-markdown.md b/docs/tutorials/gh-issues-to-markdown.md index a3f0f8f..fe33dd9 100644 --- a/docs/tutorials/gh-issues-to-markdown.md +++ b/docs/tutorials/gh-issues-to-markdown.md @@ -34,16 +34,16 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: '3.10' - name: Normalize (toolkit) run: | pip install living-doc-toolkit - living-doc normalize-issues --input doc-issues.json --output pdf_ready.json # renamed to generator-ready.json in a coming release + living-doc normalize-issues --input doc-issues.json --output generator-ready.json - name: Generate Markdown uses: AbsaOSS/living-doc-generator-markdown@v1 with: - source-path: pdf_ready.json + source-path: generator-ready.json output-path: docs/generated - name: Commit output diff --git a/docs/tutorials/gh-source-to-markdown.md b/docs/tutorials/gh-source-to-markdown.md index 98471a2..5953280 100644 --- a/docs/tutorials/gh-source-to-markdown.md +++ b/docs/tutorials/gh-source-to-markdown.md @@ -51,17 +51,17 @@ jobs: # 2. NORMALIZE - uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: '3.10' - name: Normalize (toolkit) run: | pip install living-doc-toolkit - living-doc normalize-issues --input doc-source.json --output pdf_ready.json # renamed to generator-ready.json in a coming release + living-doc normalize-issues --input doc-source.json --output generator-ready.json # 3. GENERATE Markdown - name: Generate Markdown uses: AbsaOSS/living-doc-generator-markdown@v1 with: - source-path: pdf_ready.json + source-path: generator-ready.json output-path: docs/generated # 4. COMMIT diff --git a/docs/tutorials/gh-source-to-pdf.md b/docs/tutorials/gh-source-to-pdf.md index eb6d02f..90b9edb 100644 --- a/docs/tutorials/gh-source-to-pdf.md +++ b/docs/tutorials/gh-source-to-pdf.md @@ -46,17 +46,17 @@ jobs: # 2. NORMALIZE - uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: '3.10' - name: Normalize (toolkit) run: | pip install living-doc-toolkit - living-doc normalize-issues --input doc-source.json --output pdf_ready.json # renamed to generator-ready.json in a coming release + living-doc normalize-issues --input doc-source.json --output generator-ready.json # 3. GENERATE PDF — pick the document-type for the document you want - name: Generate PDF uses: AbsaOSS/living-doc-generator-pdf@v1 with: - source-path: pdf_ready.json + source-path: generator-ready.json document-type: user-stories # or: ui-test-catalog | coverage-matrix output-path: reports/living-doc.pdf diff --git a/docs/tutorials/user-stories-to-pdf.md b/docs/tutorials/user-stories-to-pdf.md index b574f3a..4659070 100644 --- a/docs/tutorials/user-stories-to-pdf.md +++ b/docs/tutorials/user-stories-to-pdf.md @@ -28,16 +28,16 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: '3.11' + python-version: '3.10' - name: Normalize (toolkit) run: | pip install living-doc-toolkit - living-doc normalize-issues --input doc-issues.json --output pdf_ready.json # renamed to generator-ready.json in a coming release + living-doc normalize-issues --input doc-issues.json --output generator-ready.json - name: Generate PDF uses: AbsaOSS/living-doc-generator-pdf@v1 with: - source-path: pdf_ready.json + source-path: generator-ready.json document-type: user-stories output-path: reports/user-stories.pdf From 6ef57c85e08acfcfba407606268b7c6ac294accb Mon Sep 17 00:00:00 2001 From: miroslavpojer Date: Thu, 3 Sep 2026 11:32:54 +0200 Subject: [PATCH 2/2] docs(contributing): clarify branch naming conventions and include issue number requirement --- CONTRIBUTING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0633c2f..5e852d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,18 +12,18 @@ ## Branch Naming -Branches have to start with one of the allowed prefixes: `feature/`, `fix/`, `docs/`, `chore/` +Branches have to start with one of the allowed prefixes — `feature/`, `fix/`, `docs/`, `chore/` — followed immediately by the related issue number, then a short kebab-case scope: `/-`. Examples: -- `feature/add-hierarchy-support` +- `feature/128-add-hierarchy-support` - `fix/567-handle-empty-chapter` -- `docs/improve-contribution-guide` -- `chore/update-ci-python-version` - +- `docs/203-improve-contribution-guide` +- `chore/91-update-ci-python-version` + Rename if needed before pushing: ```shell -git branch -m fix/ +git branch -m fix/- ``` -Use lowercase **kebab-case** and reflect actual scope. +Use lowercase **kebab-case** and reflect actual scope. The issue number is required — CI (`check-pr-requirements`) rejects a branch without one. ## PR Naming