Debian Codegraph @

texmf-dist/doc/latex/corasdiagram/CONTRIBUTING.md

raw
1 # Contributing to `corasdiagram`
2
3 ## Project Workflow
4
5 This repository keeps the LaTeX package, documentation, examples, regression
6 tests, generated package assets, and release tooling together.
7
8 Normal lifecycle of a change:
9
10 1. Create a focused branch and make the package, docs, examples, and tests
11 changes together.
12 2. Run the local checks that match the kind of change you made.
13 3. Open a pull request with a short motivation and the verification you ran.
14 4. Merge to `main` when the change is ready.
15 5. Let the `Pages` workflow publish the documentation site from `main` when the
16 merged change affects the published docs/examples.
17 6. For a versioned release, update [`VERSION`](VERSION) and
18 [`tex/latex/corasdiagram/corasdiagram-version.tex`](tex/latex/corasdiagram/corasdiagram-version.tex)
19 together, update [`CHANGELOG.md`](CHANGELOG.md), keep the
20 `\ProvidesPackage` date in
21 [`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty)
22 aligned with that release date, push a matching tag `v<version>`, and
23 approve the `ctan-release` environment when you want the CTAN upload to
24 continue.
25
26 Workflow boundaries:
27
28 - `CI` validates pull requests and pushes to `main`/`master`.
29 - `Pages` deploys the static documentation site from `main`.
30 - `Release` runs only for pushed tags matching `v*`.
31 - The first CTAN submission is expected to be done manually. Later CTAN updates
32 can run through the tagged release workflow.
33
34 ## Canonical Sources and Generated Files
35
36 Repository-managed sources of truth:
37
38 - [`VERSION`](VERSION): canonical repository release number
39 - [`tex/latex/corasdiagram/corasdiagram-version.tex`](tex/latex/corasdiagram/corasdiagram-version.tex):
40 TeX runtime mirror of `VERSION`
41 - [`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty):
42 carries the LaTeX package header date that must match the current release
43 date in [`CHANGELOG.md`](CHANGELOG.md)
44 - [`assets/icons-src/`](assets/icons-src): canonical icon sources
45 - [`NOTICE`](NOTICE): provenance and upstream MIT notice for the vendored icon
46 sources
47 - [`ctan/metadata.json`](ctan/metadata.json): committed CTAN package metadata
48 - [`tests/corasdiagram/snapshots/`](tests/corasdiagram/snapshots): committed
49 visual regression baselines
50
51 Generated or disposable outputs:
52
53 - [`tex/latex/corasdiagram/icons/`](tex/latex/corasdiagram/icons): generated
54 runtime icon assets built from `assets/icons-src/`
55 - `dist/`: release bundles and static site output
56 - local TeX build products such as `.aux`, `.log`, generated PDFs, and
57 temporary rasterized images
58 - local scratch output under `build/`
59
60 The CTAN release bundle is the exception: it intentionally includes the
61 compiled PDFs for the canonical examples under `doc/examples/`, alongside the
62 example `.tex` sources, plus the top-level [`LICENSE`](LICENSE) and
63 [`NOTICE`](NOTICE) files.
64
65 Do not edit generated runtime icons by hand. Rebuild them from
66 [`assets/icons-src/`](assets/icons-src) when the source icons change.
67
68 ## Prerequisites
69
70 Local development expects:
71
72 - Python 3
73 - `pdflatex`
74 - `lualatex`
75 - `latexmk`
76 - `pdftoppm` for rasterized screenshot generation
77 - `cairosvg` only when rebuilding generated icon PDFs from the source SVG files
78 - `actionlint` when editing GitHub Actions workflows
79
80 ## Local Checks
81
82 ### Build the package docs and examples
83
84 Build the minimal example:
85
86 ```bash
87 TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-minimal.tex
88 ```
89
90 Build the full demo:
91
92 ```bash
93 TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-demo.tex
94 ```
95
96 Build the manual:
97
98 ```bash
99 (cd docs && TEXINPUTS=../tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error corasdiagram-doc.tex)
100 ```
101
102 Build with LuaLaTeX:
103
104 ```bash
105 TEXINPUTS=tex/latex//: TEXMFVAR=/tmp/corasdiagram-texmf TEXMFCACHE=/tmp/corasdiagram-texmf \
106 lualatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-minimal.tex
107 ```
108
109 ### Run semantic and visual regressions
110
111 Run the semantic failure fixtures:
112
113 ```bash
114 python3 tools/check_negative_tests.py --engine pdflatex
115 ```
116
117 Run the visual regression checks:
118
119 ```bash
120 python3 tools/check_visual_regressions.py
121 ```
122
123 Regenerate committed snapshot baselines after an intentional notation or layout
124 change:
125
126 ```bash
127 python3 tools/check_visual_regressions.py --update
128 ```
129
130 ### Rebuild assets and use editing tools
131
132 Rebuild generated runtime icons from the canonical SVG sources:
133
134 ```bash
135 python3 tools/build_coras_icons.py
136 ```
137
138 Run the local browser-based anchor editor:
139
140 ```bash
141 python3 tools/coras_anchor_editor.py
142 ```
143
144 Smoke-test the parser/writer logic for the anchor editor:
145
146 ```bash
147 python3 -m unittest tests/test_coras_anchor_editor.py
148 ```
149
150 ### Check packaging and release helpers
151
152 Verify the versioning story:
153
154 ```bash
155 python3 tools/check_release_tag.py
156 ```
157
158 Build the manual and the canonical example PDFs before assembling the release
159 bundle:
160
161 ```bash
162 TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-minimal.tex
163 TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-demo.tex
164 TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-high-level-analysis-table.tex
165 TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-website-examples.tex
166 ```
167
168 Then build the CTAN release bundle:
169
170 ```bash
171 python3 tools/build_release.py --doc-pdf docs/corasdiagram-doc.pdf
172 ```
173
174 Optionally validate the rebuilt archive against the CTAN API before uploading
175 it manually:
176
177 ```bash
178 python3 tools/upload_ctan.py \
179 --archive "dist/corasdiagram-$(cat VERSION).zip" \
180 --uploader "Fabian Robert Smith" \
181 --email "[email protected]" \
182 --update false \
183 --validate-only
184 ```
185
186 Generate the static documentation site after compiling the examples and manual:
187
188 ```bash
189 python3 tools/build_site.py \
190 --docs-pdf docs/corasdiagram-doc.pdf \
191 --demo-pdf examples/corasdiagram-demo.pdf \
192 --minimal-pdf examples/corasdiagram-minimal.pdf \
193 --website-examples-pdf examples/corasdiagram-website-examples.pdf \
194 --analysis-table-pdf examples/corasdiagram-high-level-analysis-table.pdf
195 ```
196
197 If you edit workflow files, lint them:
198
199 ```bash
200 actionlint .github/workflows/ci.yml .github/workflows/pages.yml .github/workflows/release.yml
201 ```
202
203 ## Change Checklist by Change Type
204
205 ### Public API or notation change
206
207 - update the package source, examples, and the manual together
208 - update [`README.md`](README.md) if the user-facing setup, supported API, or
209 workflow summary changed
210 - update [`CHANGELOG.md`](CHANGELOG.md) for public-facing behavior changes
211 - run the relevant TeX builds plus semantic and visual checks
212 - add or update negative semantic fixtures if the change affects validation
213
214 ### Visual or layout change
215
216 - run `python3 tools/check_visual_regressions.py`
217 - update committed baselines in the same change with `--update`
218 - keep snapshot changes scoped to the intentional visual difference
219 - recheck demo/manual/example output after updating baselines
220
221 ### Icon or source asset change
222
223 - edit only files in `assets/icons-src/`
224 - rebuild the generated runtime icons with `tools/build_coras_icons.py`
225 - verify both color and `iconset=bw` outputs still compile cleanly
226 - update snapshots, examples, and docs if the rendered symbols changed
227
228 ### Docs-only change
229
230 - update the relevant repo docs and/or the package manual
231 - build the manual if `docs/corasdiagram-doc.tex` changed
232 - keep repo-facing contributor/runbook material in `README.md` and
233 `CONTRIBUTING.md`, not in the package manual
234
235 ### Release or version change
236
237 - update [`VERSION`](VERSION)
238 - update
239 [`tex/latex/corasdiagram/corasdiagram-version.tex`](tex/latex/corasdiagram/corasdiagram-version.tex)
240 to the same value
241 - update [`CHANGELOG.md`](CHANGELOG.md)
242 - update the `\ProvidesPackage` date in
243 [`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty)
244 to match the release date
245 - run `python3 tools/check_release_tag.py`
246 - create and push the matching tag `v<version>`
247 - approve the `ctan-release` environment when you want the CTAN upload job to
248 proceed
249
250 ## Versioning and Releases
251
252 The repository uses one canonical versioning story:
253
254 - `VERSION` is the canonical repository release number
255 - `corasdiagram-version.tex` is the TeX runtime mirror and must match `VERSION`
256 - the `\ProvidesPackage` date in `corasdiagram.sty` must match the current
257 dated `CHANGELOG.md` release entry
258 - release tags must be `v<version>`
259 - the `Release` workflow verifies the version/tag story and package header date
260 before building or publishing anything
261 - CTAN upload versioning is derived as `<VERSION> <release-date>`, where the
262 release date comes from the matching dated entry in [`CHANGELOG.md`](CHANGELOG.md)
263
264 Release behavior:
265
266 - a pushed `v*` tag builds the release archive and GitHub release assets
267 - the same tag starts the gated CTAN publication job
268 - the `ctan-release` environment contains `CTAN_UPLOADER_NAME` and
269 `CTAN_UPLOADER_EMAIL`
270 - the `ctan-release` environment requires review by `smithfabian`, so the CTAN
271 upload job cannot read those values or continue without approval
272 - [`ctan/metadata.json`](ctan/metadata.json) keeps the committed CTAN package
273 metadata, including the selected topics (`diagram`, `pgf-tikz`) and the
274 announcement URL used for manual/reference purposes
275 - the current API-based uploader submits only CTAN fields that the CTAN upload
276 API supports, so the committed `announce` URL is not sent automatically
277 - non-empty CTAN URL-role fields must be unique across `home`, `repository`,
278 `development`, `bugtracker`, `support`, and `announce`
279
280 Pages behavior:
281
282 - Pages deployment is handled by the dedicated `Pages` workflow
283 - pushes to `main` can update the documentation site
284 - tagged releases do not deploy Pages directly
285
286 ## When to Update Docs, Examples, and Tests
287
288 Update the docs/examples/tests in the same change when:
289
290 - public behavior changes: update the manual, examples, and relevant README
291 sections
292 - semantic validation changes: add or update negative tests
293 - visual rendering changes: refresh committed visual baselines
294 - icon changes: update source icons, generated runtime icons, and any examples
295 or snapshots that show them
296 - release workflow or contribution workflow changes: update both
297 [`README.md`](README.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md)
298
299 ## Coding and Documentation Style
300
301 - Prefer the semantic CORAS macros in docs and examples.
302 - Keep low-level primitives available for compatibility unless a deprecation is
303 explicitly planned and documented.
304 - Default to ASCII in source files unless there is a clear reason not to.
305 - Keep CI-friendly commands shell-friendly and reproducible from the repository
306 root.
307 - Do not rely on undocumented local steps for releases, snapshots, or icon
308 generation; if a workflow matters, document it here or in the relevant script
309 header/docstring.
310
311 ## Pull Requests
312
313 Pull requests should:
314
315 1. stay focused on one change or one closely related set of changes
316 2. explain the motivation briefly
317 3. list the verification that was actually run
318 4. update docs/examples/tests together when public behavior changed
319 5. update [`CHANGELOG.md`](CHANGELOG.md) when the public API or release-visible
320 behavior changed