diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3697c0bde..8afd9fec8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -835,3 +835,9 @@ arguments trigger each test case at runtime: In this case, `in 0:` and `in 1:` contain the enumeration name, which corresponds to a test case triggered by the `Check` procedure. + +## Git workflow + +For details about the git workflow of this repository, see +[GIT_WORKFLOW.md](GIT_WORKFLOW.md). + diff --git a/GIT_WORKFLOW.md b/GIT_WORKFLOW.md new file mode 100644 index 000000000..29bc641a1 --- /dev/null +++ b/GIT_WORKFLOW.md @@ -0,0 +1,122 @@ +# Git workflow (suggested) + +> These are *suggested* recommendations for branch naming and commit messages. +> They are not mandatory, but following them keeps the history consistent and +> reviewable. + +## Branch naming + +Development work happens on a task-specific *topic branch* created off the +default branch (`main`), never directly on `main`. Two top-level forms are used, +selected by whether an issue exists: + +``` +dev/issue//[/] # an issue exists +dev/topic///.../[/] # no issue +``` + +- `issue` and `topic` are literal selectors. +- `` is a short, hyphenated slug naming the specific work (for + example `multi-project-structure` or `keyboard-nav`). It is what distinguishes + this branch from other work in the same area. +- `` is `YYYY-MM-DD`, optional, placed at the end so branches group by + topic (the date is the leaf differentiator). +- Use the proper name for a known component (`compile_blocks`, + `github_actions`); use hyphens for free-text descriptors (`multi-project`). + +For the learning material, the only top-level distinction that matters is +whether the work touches *content* or *infrastructure*: + +- `content` -- ReST authoring (what readers read). Sub-areas mirror the + `content/` tree: + - `dev/topic/content/general/[/]` -- cross-cutting work + spanning several courses, or site-wide editorial passes + - `dev/topic/content/courses//[/]` + - `dev/topic/content/labs//[/]` + - `dev/topic/content/booklets//[/]` + +- `infrastructure` -- everything that is *not* ReST content authoring. This + includes everything under `frontend/` (the TypeScript widget, SCSS, webpack, + the Sphinx plugins, the Makefile) as well as CI and the VM setup. Sub-area is + the component: + - `dev/topic/infrastructure/sphinx/[/]` + - `dev/topic/infrastructure/compile_blocks/[/]` + - `dev/topic/infrastructure/github_actions/[/]` + - `dev/topic/infrastructure/widget/[/]` + - `dev/topic/infrastructure/vagrant/[/]` + - `dev/topic/infrastructure/pnpm/[/]` + +### Feature sub-branches (suggested for bigger implementations) + +For larger work split into multiple phases or work items, a *main + feature +branches* approach is recommended. The topic branch above becomes the +integration branch by appending `/main`, and each work item gets its own feature +branch by appending `/feat/`: + +``` +/main # integration branch for the whole topic +/feat/ # one per feature / work item +``` + +For example, with a topic root of +`dev/topic/infrastructure/pnpm/migration/2026-05-25`: + +``` +dev/topic/infrastructure/pnpm/migration/2026-05-25/main +dev/topic/infrastructure/pnpm/migration/2026-05-25/feat/remove-yarn +dev/topic/infrastructure/pnpm/migration/2026-05-25/feat/lock-file +``` + +Each feature branch is merged back into `/main` with a non +fast-forward merge (`git merge --no-ff`), using the message +`Merge feat/: `. The whole topic is then opened as a +single pull request against `main`. + +For small, single-purpose changes the feature branches can be omitted: work +directly on the topic branch (without the `/main` suffix). + +## Commit messages + +Subject lines carry a canonical tag identifying intent, followed by a colon and +an imperative description (up to 72 characters): + +``` +: +``` + +- Use a colon (`Sphinx: ...`), not brackets. +- Use the canonical spelling consistently -- avoid ad-hoc variants + (`Editorial change:`, `Editorial changes:`, `GitHub actions:`, and so on). +- Issue references go in the body (`Refs #123` / `Closes #123`), not the + subject. + +The tag axis differs by area. *Content* tags name the *nature* of the change +(the area is always content); *infrastructure* tags name the *component* touched +(the verb in the description carries add/fix/update). + +| Area | Tag | Use | +|-----------------|-----------------|-----------------------------------------------------| +| content | `New content:` | adding new material | +| content | `Editorial:` | wording, style, typos, grammar, prose restructuring | +| content | `Correction:` | fixing an error in an example or explanation | +| infrastructure | `Frontend:` | general frontend code | +| infrastructure | `Widget:` | the interactive widget | +| infrastructure | `SCSS:` | styles | +| infrastructure | `Sphinx:` | Sphinx plugins / extensions / config | +| infrastructure | `Python:` | Python tooling / modules | +| infrastructure | `Test script:` | test tooling | +| infrastructure | `CI:` | GitHub Actions / CI | +| infrastructure | `Vagrant:` | VM provisioning | +| infrastructure | `Makefile:` | build pipeline | +| infrastructure | `Docs:` | repository docs (README, CONTRIBUTING, and so on) | + +Example: + +``` +Sphinx: fix anchor resolution across multi-project builds + +The multi-project layout broke cross-references because <...>. This restores +<...> and adds a regression check. + +Refs #1361 +```