Add a release-triggered workflow to the GitHub Source → Markdown tutorial
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 78/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- github-actions, python, yaml
- Domain
- ci-cd, documentation
Research direction
Read docs/tutorials/gh-source-to-markdown.md and the existing § 2 workflow, then add chapter 5 and the release workflow at .github/workflows/living-doc-release.yml. Explain the release trigger, asset uploads, and the listed caveats; finish by running the documentation and example checks named in the issue and proving the workflow with a published pre-release that shows six assets.
Written by the indexing model from the issue text.
Description
Summary
Add a chapter to docs/tutorials/gh-source-to-markdown.md whose workflow attaches the six files to each published GitHub release.
Current State (If Updating)
- The tutorial's workflow runs on a push to
mainand onworkflow_dispatch, and commitsdocs/living-doc/. - A nightly
scheduleis a one-line variant (§ 2). - No page shows a run started by a release, or documents attached to one.
Proposed Changes
- A new chapter
## 5. Attach the documents to a release, with its## Contentsline.## Purposesays the documents are "refreshed on every push or attached to each release". - A second workflow,
.github/workflows/living-doc-release.yml, shown as a variant of § 2. It keeps § 2's checkout, Python setup and steps 1–3, changeson:, dropsconcurrency:and replaces step 4. It copies none of § 2's steps, so a tag bump edits one place.
name: Living Documentation release
on:
release:
types: [published]
jobs:
living-doc:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
# The checkout, the Python setup and steps 1–3 (COLLECT, NORMALIZE, GENERATE) exactly as in § 2
# 4. ATTACH each document and its run report to the release
- name: Attach the documents to the release
env:
GH_TOKEN: ${{ github.token }}
TAG: ${{ github.event.release.tag_name }}
run: gh release upload "$TAG" docs/living-doc/* --repo "$GITHUB_REPOSITORY" --clobber
- One line each on the page, under "On each published release:":
- The checkout is the release's tag, so the documents show the code as released.
- Step 4 attaches the six files to the release as assets;
--clobberreplaces them when the run is re-run. - Nothing is committed: the checkout is a tag, not a branch, so there is no branch to push to.
- The workflow has no
concurrency:block: in § 2'sliving-docgroup, a push would cancel a release run. publishedalso fires for a pre-release;types: [released]leaves pre-releases out.- A release published with the job's token starts no run; publish it by hand or with another token.
- To name the release in a title, set a render step's
document-title, for exampleTechnical project ${{ github.event.release.tag_name }}(link toliving-doc-generator-markdowndocs/action.md#inputs).
- Proof before merge: one run on a published pre-release in a repository that holds the tutorial's inputs, for example a fork of
living-doc-testbed. The release shows the six assets, and the PR links the run. A pull-request check cannot start areleaseevent, so this is a one-off run.
Dependencies / References
- #106: the same one-off proof, for § 2's workflow.
- #133: the by-tag workflow runs § 2 only; it cannot cover this chapter.
Additional Context
A draft of the chapter passed pytest tests/docs tests/examples, tests/examples/examples_check.py, tests/docs/retired_names_check.py --strict and lychee with fragments on the page. § 2's workflow with the variant applied parses as YAML, with the steps in order. The draft was not committed.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 16m
- Merged PRs (30d)
- 24
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from AbsaOSS/living-doc
-
type:tech-debt
Difficulty 1/5 Under an hour Newbie friendliness 78/100
AbsaOSS/living-doc#133 ·
Maintainers usually reply within 1 day
-
type:tech-debt
Difficulty 1/5 1-3 hours Newbie friendliness 85/100
AbsaOSS/living-doc#130 ·
Maintainers usually reply within 1 day
-
type:tech-debt
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
AbsaOSS/living-doc#129 ·
Maintainers usually reply within 1 day
-
type:tech-debt
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
AbsaOSS/living-doc#119 ·
Maintainers usually reply within 1 day
-
enhancement module:data scope:qa type:feature
Difficulty 5/5 Over a week Newbie friendliness 35/100
AbsaOSS/living-doc#143 ·
Maintainers usually reply within 1 day
All issues in AbsaOSS/living-doc
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
mozilla-ai/cq#601 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
intcomma returns exponential notation for large floatsPossibly taken @Omarinho12345 claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
python-humanize/humanize#521 ·
Maintainers usually reply within 1 day
-
LUCJ pass manager raises NoEdgeBetweenNodes when an edge is bad for two two-qubit gatesPossibly taken @hat-im claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
opensubtitlescom: provider rejects pt-PT even though its own converter maps itPossibly taken @paulo-0308 claimed this today. Open
Difficulty 1/5 Under an hour Newbie friendliness 88/100
Diaoul/subliminal#1405 ·