Project
Contributing
Bugs, questions and ideas
They go in the issue tracker, gitlab.com/gunkslab/desk-issues.
Search it first; then open an issue saying what you ran, what you expected and what happened, with the output of
./gunkslab doctor and the log from logs/ (./gunkslab logs writes them). Opening one needs a GitLab account.
There’s no promise on how soon it’s answered.
A security problem goes there too, but as a confidential issue, hidden from the public: SECURITY.md says how.
The checks
scripts/check runs every check CI runs, on your machine, in containers: the protocol, the unit tests, the
firmware, the bench programs, the scenarios, the shell scripts, the page’s scripts, the generated docs, and the
end-to-end test (which needs scripts/broker up). CI (.gitlab-ci.yml) runs the same on every merge request and on
main. Each one on its own is in the scripts reference.
Four more jobs run on merge requests only. They guard the checks themselves, and each one compares the branch with
where it left main (.gitlab/ci/guards.yml):
guard:ratchetcounts the ignore comments (# noqa,# nosec,shellcheck disableand the like), the skipped tests, and the allowed failures in the pipeline. A merge request can take them out or move them. It fails if it leaves more than there were.guard:gateslists the checks a merge request changes: the pipeline, the scripts that run it, the accepted security findings. It never fails. It shows as a warning on the pipeline, so the change gets read before the merge.guard:fix-testasks a bug fix for a test. It knows a fix by a title that starts with “fix”, also after the area (“station: fix the turn”), or a branch that starts withfix/. It fails if the merge request changes no test.guard:code-testasks a code change for a test, whatever its title says. It fails if the merge request changes code in a part that has tests and adds or changes no test. The parts are underCODE_PATHSin.gitlab-ci.yml: the Python parts, the page’s scripts, the broker’s rules and settings, the firmware libraries with tests, and the protocol’s schemas. A change that needs no test, a reworded comment say, says so in the merge request. A maintainer then lets it through with the labelcode-test-override, and it shows as a warning.
A merge request
The merge request template asks for:
scripts/checkpassing;- the docs changed with the code, and any output shown in them real, from running it;
- for a change to the network, the protocol, the firmware or a container, the security questions in Security: before merging.
The docs
The docs are in docs/, one folder per section. Each section’s README lists its pages in order, in a table; the
site (gunkslab.com) reads those tables for its menu. Each page is one kind:
- Tutorials teach, in order, and end with “Check yourself”.
- Guides get one job done, and don’t teach.
- Concepts explain why, with no steps.
- Reference is exact and complete, to look up. Pages written from the code (
docs/gen.py) are never edited by hand: change the code, and runpython3 docs/gen.py.
A new page goes in one section, and in that section’s table.
A step that differs by OS gets a tab for each, between two comments, one #### heading per tab. Use these four
headings, in this order, so the site keeps the reader’s pick from page to page:
<!-- tabs: os -->
#### macOS
#### Ubuntu / Debian
#### RHEL / Fedora
#### Windows
<!-- /tabs -->
GitLab hides the comments and shows each tab under its heading. The site turns them into tabs, opened on the reader’s OS.
python3 docs/lint.py checks the pages for what a reader trips on (CI runs it too). A step for one OS outside an OS
tab group fails it. Its warnings are rules on trial, and each fails it once the docs are clear of it: a step with
commands and nothing saying what you’ll see, the same long command on two pages, a tutorial without “Check
yourself”.
A release
A release is a tag, vX.Y.Z, on main, where VERSION says X.Y.Z. Between releases VERSION says what’s next with
-dev after it (0.2.0-dev), and the release notes have a section for it, ## 0.2.0 (not released yet), that each merge request adds to: what’s new, what changed (anything that works differently from the last
release), the known issues, and how to move to it.
To release:
- Run the install checklist on every platform, and record the runs. On a branch:
VERSIONloses its-dev; the release notes’ section, and Known issues’, get the date in place of “not released yet”.scripts/checkpasses. Merge it. - Tag main:
git tag -a vX.Y.Z -m "gunkslab X.Y.Z", and push the tag. Its pipeline runs every check again, and the docs job fails if the tag isn’tvandVERSION. - Make the GitLab release from the tag, with that section of the notes as its text.
- On a branch:
VERSIONbecomes the next version with-dev, and the notes get its section. Merge it.