For admins¶
Admins review and merge pull requests and keep the build working. Repository admins today: @costantinoai, @kschevenels and @opdebeeck.
Review and merge a pull request¶
- Open the pull request from the Pull requests tab.
- Wait until all checks pass. The bot comment has the check report and links to the preview of each changed page.
- Read the changes in Files changed. Ask for changes in a review, or push small fixes yourself (see Edit a contributor's pull request).
- Approve, then click Squash and merge.
The pull request becomes one commit on main. Its author is the person who opened the pull request; anyone else who committed is added as co-author. GitHub deletes the branch, and the merge starts the deploy: the live site updates a few minutes later. If you had the branch on your computer, delete it there with git branch -D <branch>.
Merging your own pull request
You cannot approve your own pull request. Ask another member of reviewers to approve it, or bypass the review as an admin: tick the bypass box under the merge button, or run gh pr merge <number> --squash --admin. Bypass only when all checks have passed.
Edit a contributor's pull request¶
You can push fixes to a pull request before merging it.
- Branch in this repository (web editor
user-patch-Nbranches, Advanced workflow):gh pr checkout <number>, edit, commit,git push. Or edit the files on GitHub, in the pull request's Files changed tab. - Fork: the same works when the pull request has Allow edits by maintainers ticked (
gh pr view <number> --json maintainerCanModify). Pushing there writes to the contributor's fork. If the box is not ticked, ask the contributor to tick it, or to move the change to a branch in this repository.
Tell the contributor to pull before they continue, since their copy no longer has your commits.
The rules on main¶
One organisation ruleset, default-branch, covers the default branch of every HOPLAB-LBP repository, this wiki included, and every new repository from the moment it is created. Change it under the organisation's Settings > Rulesets.
- Changes reach the default branch only through a pull request, with one approval from a member of the
reviewersteam. The team is asked to review automatically, but only on repositories it has access to, and only while it stays visible. - New repository: add the team right after creating it (Settings > Collaborators and teams > Add teams >
reviewers, role Write). Without it, pull requests are blocked and nobody is asked to review them. - Nobody can push to the default branch directly, admins included. Admins can bypass the review, but only when merging a pull request.
- A new push to the pull request dismisses earlier approvals.
- Force pushes and deleting the default branch are blocked.
- Squash merge is the only merge method.
The wiki also has a ruleset of its own, pr-checks (Settings > Rules > Rulesets of this repository): on main, the check check-and-report must pass before a pull request can be merged. Organisation admins can bypass it when merging, for emergencies only: when GitHub never started the checks (push a new commit or close and reopen the pull request first) or GitHub Actions is down. A pull request opened by the bot (Autofix docs) starts no checks: close and reopen it.
What runs where¶
| Workflow | When | What it does |
|---|---|---|
| PR checks | Every pull request | Runs the checks (check-and-report, required), posts fix suggestions and publishes the preview: see Checks, suggestions and previews |
| Remove PR preview | A pull request closes | Deletes its preview from gh-pages |
| Post PR check report | After each PR checks run | Posts the report as a comment on the pull request |
| Automation tests | Pushes to main that touch workflows, scripts, tests or check settings; also by hand |
Tests the scripts and lints the workflows (pull requests get the same in PR checks) |
| Deploy to GitHub Pages | Every push to main; also by hand |
Builds the site with mkdocs-ci.yml and publishes it on the gh-pages branch, leaving the previews in pr-preview/ in place. When a deploy fails, it opens an issue labelled deploy-failure and assigned to @costantinoai; the next successful deploy closes it |
| Weekly link check | Mondays at 06:00 UTC; also by hand | Checks every link on the wiki and keeps one issue labelled link-check with the broken ones, assigned to @costantinoai; closes it when all links work again. Also deletes any preview left on gh-pages for a pull request that is no longer open |
Dependabot (.github/dependabot.yml) |
Once a month | Opens one pull request that updates all the actions the workflows use to their newest versions. Read the release notes of any new major version before you merge it |
| Manage Docs Tags and Issues | Every push to main, every day at 07:00 UTC, issue comments; also by hand |
Keeps one issue per page with its TODO, NOTE and PLACEHOLDER tags |
| Autofix docs | Only by hand | Runs the auto-fixes on all of main and opens a pull request with them. Checks do not start on a pull request the bot opens: close and reopen it to run them |
To run one by hand: Actions tab, pick the workflow, Run workflow.
Checks, suggestions and previews¶
check-and-reportruns the spell check, Markdown and YAML lint, MkDocs build and syntax check, and the script tests and workflow lint when those change. The link check only warns. The job writes the report thatpr-comment.ymlposts.find-fixesruns the safe fixers on a copy of the pull request, with no token;suggest-fixesposts each change as a review suggestion on the lines it covers (scripts/post_suggestions.py, from the base branch). The fixers are the ones inscripts/plusmarkdownlint-cli2 --fixandtypos --write-changes;scripts/fix_links.pyhandles links with one clear target. The bot never pushes.previewpublishes the built site atpr-preview/pr-<number>/ongh-pages, with a banner, no search indexing and no analytics. A push that breaks the build takes the old preview offline; closing the pull request removes it, and the weekly link check removes any left over.- Forks and Dependabot get the checks but no suggestions and no preview: their token is read-only.
- Every pull request gets the checks, whatever it changes, so none waits forever on the required check.
gh-pages(the live site) is not protected. Never push to it by hand: every deploy ofmainrewrites it.
Two build configurations¶
mkdocs.ymlis what contributors use withmkdocs serve. It has no plugin that needs git.mkdocs-ci.ymlstarts withINHERIT: mkdocs.ymland adds the plugins that read the git history: the last update and the contributors at the bottom of each page. The PR build (scripts/docs_ci_check.sh) and the deploy use it.- Its
plugins:list replaces the one inmkdocs.ymlinstead of extending it. When you add or remove a plugin inmkdocs.yml, make the same change inmkdocs-ci.yml. - To preview the site exactly as it is published:
bash scripts/prepare_docs.sh && mkdocs serve -f mkdocs-ci.yml.
Adding or upgrading a plugin¶
- Add it to
requirements.txtwith a version range, for examplemkdocs-glightbox>=0.5,<0.6, so CI never jumps to a new major version on its own. - A plugin that needs git, network access or system libraries while building goes in
mkdocs-ci.ymlonly. Any other plugin goes in both files. - A plugin in
mkdocs.ymlstopsmkdocs servefor everyone who has not installed it. Say so in the pull request and tell the lab to runpip install -r requirements.txtonce. - Use only options that older versions of the plugin know too: contributors with an older environment (Python 3.9) get older releases, and an unknown option fails the strict build.
The Contribute pages¶
docs/contribute.md(Quick start) is a copy ofREADME.md, made byscripts/prepare_docs.shbefore every build. EditREADME.md, neverdocs/contribute.md.- In
README.md, link to wiki pages with paths from the repository root, such asdocs/contribute/admins.md. They work on GitHub, andprepare_docs.shturns them into wiki links in the copy. - The other Contribute pages, such as this one, are normal wiki pages in
docs/contribute/.
Names under each page¶
- When a contributor shows up under a GitHub handle, or twice, add a line to
.mailmap: their full name, their GitHub no-reply address (which gives the avatar) and the e-mail of their commits. - Bots and AI agents are not listed as contributors. A new one goes under
ignore_authorsinmkdocs-ci.yml, with its commit e-mail in lower case.
When a check flags something that is fine¶
| Flag | Fix |
|---|---|
| Spell check rejects a real word or name | Add it to _typos.toml |
| Link check fails on a site that blocks bots (login page, CAPTCHA, error 400) | Add a pattern to exclude in .lychee.toml, with a comment that says why |
| Markdown lint rejects an HTML element | Add it to allowed_elements under MD033 in .markdownlint-cli2.yaml |
| The strict build warns about a shallow clone | Check out with fetch-depth: 0, as the two building workflows already do |