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

Aperta Adatta ai principianti
#140 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
78/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
github-actions, python, yaml

Direzione di ricerca

Leggi docs/tutorials/gh-source-to-markdown.md e il workflow esistente nella § 2, poi aggiungi il capitolo 5 e il workflow di release in .github/workflows/living-doc-release.yml. Spiega il trigger della release, i caricamenti degli asset e le avvertenze elencate; termina eseguendo i controlli della documentazione e degli esempi indicati nell’issue e dimostrando il workflow con una pre-release pubblicata che mostri sei asset.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Python
Stelle
0
Fork
0
Merge medio
6h 16m
PR unite (30g)
24

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di AbsaOSS/living-doc

Tutte le issue di AbsaOSS/living-doc

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.