Add a release-triggered workflow to the GitHub Source → Markdown tutorial

Open Beginner friendly
#140 0 comments 0 reactions 0 assignees View on GitHub

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

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

type:documentation
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 main and on workflow_dispatch, and commits docs/living-doc/.
  • A nightly schedule is 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 ## Contents line. ## Purpose says 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, changes on:, drops concurrency: 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; --clobber replaces 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's living-doc group, a push would cancel a release run.
    • published also 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 example Technical project ${{ github.event.release.tag_name }} (link to living-doc-generator-markdown docs/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 a release event, 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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/living-doc

All issues in AbsaOSS/living-doc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.