Contributing¶

Magellanic accepts contributions on GitHub and GitLab equally. Open your pull request (GitHub) or merge request (GitLab) on whichever platform you prefer. Both are reviewed by the same maintainers under the same rules, and a merge bot lands approved changes on both platforms, so the two repositories always have the same history.

Your first contribution¶

Look for issues labelled good first doc on either platform: small, well-defined tasks such as adding a missing distribution tab, a reference table row, or a glossary entry, each with a clear "done when". Spotted a wrong command? Open a Content defect issue; if following the page could cause harm, report it privately as described in SECURITY.md.

Issue templates (New page, Content defect, Good first doc) and the pull/merge request template are the same on GitHub and GitLab.

Before you write¶

Decide what kind of page you're writing using the Diátaxis compass. Every page serves exactly one need: a tutorial, a how-to guide, reference, or explanation.
Check whether the page already exists, or should be an improvement to an existing page.
For anything substantial, open an issue first so the type, domain and scope can be agreed.

Set up¶

You need mise, make and git. mise installs the pinned tools from mise.toml (uv, Lefthook, Node.js and markdownlint-cli2), and uv installs the Python toolchain from uv.lock. Run mise trust once after cloning. Then:

make install          # pinned tools via mise, Python toolchain from uv.lock, git hooks
make serve            # live preview at http://localhost:8000

Write¶

make new TYPE=how-to DOMAIN=storage SLUG=extend-lvm-volume

This creates docs/how-to/storage/extend-lvm-volume.md from the matching template. Fill in every TODO, run make nav to add the page to the navigation and its section's landing page, and follow the style guide.

Domains and distribution identifiers are listed in scripts/taxonomy.toml.

Check¶

make check    # Markdown lint, Vale, spelling, front matter, plugin allow-list, licensing, Python lint and tests
make build    # strict build: fails on broken links, anchors or config warnings

Tutorials and how-to guides are also verified in disposable labs before they're committed: see Command verification and Lab environments.

CI runs exactly the same commands on both platforms. make install also installs git hooks (Lefthook): staged files are checked on every commit, the commit message must carry a DCO sign-off, and the strict build runs before every push.

Changing the scripts¶

The Python in scripts/ has tests in tests/ (ADR-020). If you change a script, update its tests in the same commit:

make lint-py   # Ruff: lint and format check
make test      # pytest with branch coverage

make test fails if the total coverage falls below 95 % or any script's falls below 90 %. A new script needs tests before it can be committed. Tests never use the network, the labs or the repository's own files: they work in temporary folders and replace external commands with fakes. The commit hook runs both whenever a script, a test or the Python configuration changes.

Submit¶

Sign off every commit to certify the Developer Certificate of Origin: git commit -s.
Open a PR or MR. CI runs, and a preview of the site is available from the pipeline.
A maintainer or domain owner reviews it against the review checklist. Once it's approved and green, a maintainer marks it merge-ready and the merge bot lands it on both platforms. Both sites then update automatically.

By contributing, you agree that your contribution is licensed under the project's licences: CC BY-SA 4.0 for documentation and MIT-0 for code. See Reusing this content.

Review checklist¶

The same checklist appears in every pull request and merge request.