| 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 |