Setup
Cloning the GWR repo
Some packages within the GWR workspace, such as the -sys packages, use git
submodules to make source code from other repositories avaliable. When cloning
this repo passing the --recurse-submodules option is sufficient to make
everything required avaliable. The --shallow-submodules can also be passed.
Tooling
All of the required tooling to build and use, and to develop GWR can be installed using the scripts included within the repo. These scripts are designed to be used by both users and the CI system.
Dependencies will be installed using package managers where possible, with APT being used on Linux and Homebrew on macOS (Homebrew itself will be installed as required if not already avaliable). Various cross-platform package managers are also used, including rustup, Cargo, and npm.
See the Using GWR Packages and Developing GWR Packages sections for further details on these install scripts.
Rust Tools
The correct Rust toolchain will automatically be selected and used by rustup
when commands are executed from within the GWR directory (or below). This
behaviour is controlled by the the rust-toolchain.toml file.
Using GWR Packages
For users of the GWR packages a stable Rust toolchain is required, as well as
external tools such as Asciidoctor, Cap’n Proto, and mdBook. All of the
required build dependencies can be installed by running:
./.github/actions/install-build-dependencies/install.sh
important
To ensure that the correct Rust toolchain is used the script must be executed from within the GWR directory.
tip
Although the script is interactive, selecting the default option (Enter) at every step is a reasonable choice and will result in a working environment.
note
Some of the actions taken by the script may request elevated permissions via
sudo.
Developing GWR Packages
For developers of the GWR packages both stable and nightly Rust toolchains
are required, as well external tools such as cargo-deny, cargo-about
cargo-semver-checks, Cocogitto, prek, Prettier, and Release-plz. All
of the required development dependencies can be installed by running:
./.github/actions/install-dev-dependencies/install.sh
important
To ensure that the correct Rust toolchain is used the script must be executed from within the GWR directory.
tip
Although the script is interactive, selecting the default option (Enter) at every step is a reasonable choice and will result in a working environment.
note
Some of the actions taken by the script may request elevated permissions via
sudo.
Finally the Git hooks need to be installed within the cloned copy of the GWR repo:
prek install
Branching the Repo
The process for branching the repo is codified by the Branching item of the Feature/fix development checklist.
Changes to GWR packages are developed on branches separate to main (the
default) branch of the repo, and then incorporated when complete via a pull
request.
Push-specific CI runs only on main, experimental and branches whose names
begin with feature-, for example, feature-new-example-app.
note
The experimental branch will never be merged into the main branch. However
updates from main may be merged into experimental via a pull request.
Before opening a pull request, a feature branch must be renamed to remove the
feature- prefix. Use of the pr- prefix, for example, pr-new-example-app is
the usual convention. Branches named without the push-specific prefixes are
preferred as they do not cause the push-specific CI workflow to run, avoiding a
duplicate run alongside the pull request-specific workflow.
Draft pull requests create only skipped CI job entries, so no runner work is performed. CI runs when a pull request is opened as ready for review, when a draft is marked ready, when a ready pull request is reopened, and after each subsequent push or rebase. Moving a pull request back to draft cancels any in-progress CI run.
---
title: GWR git branching scheme
config:
theme: 'base'
gitGraph:
parallelCommits: false
---
gitGraph:
checkout main
commit id: "initial commit"
branch experimental
branch pr-publish-docs
commit id: "infra: publish built documentation"
checkout main
merge pr-publish-docs
checkout experimental
branch feature-visualiser-experiment
commit id: "feat: add visualiser package"
commit id: "feat: component hierarchy viz"
branch pr-visualiser-experiment
commit id: "feat: component hierarchy visualisation"
checkout experimental
merge pr-visualiser-experiment
checkout main
branch feature-visualiser
commit id: "feat: component visualisation"
commit id: "feat: model visualisation"
branch pr-visualiser
commit id: "feat(gwr-visualiser): component visualisation"
commit id: "feat(gwr-visualiser): model visualisation"
checkout main
merge pr-visualiser
checkout experimental
branch pr-updates-from-main
commit id: "chore: remove experimental visualiser"
merge main
checkout experimental
merge pr-updates-from-main
This diagram is read left to right and top to bottom (like the Network graph view of GitHub). Pull requests are shown as if they land using merge commits, single points (the circles with white centres) on the graph, though in reality they will be rebased without squashing their individual commits.
Committing a Change
The process for creating commits is codified by the Commits item of the Feature/fix development checklist.
During the commit process a number of different hooks will be invoked by prek:
- The Cocogitto tool is used to lint the text of the commit message, ensuring that it adheres to the Conventional Commits specification.
- All packages within the workspace will be checked for adherence to proper
semantic versioning using cargo-semver-checks.
- As this can be a time consuming set of checks to run, by default, they are only performed by the CI system.
- The checks can be run locally with:
prek run --all-files cargo-semver-checks
- All dependencies will be checked for vulnerabilities and compatible licensing using cargo-deny.
- The licenses of all dependencies will collated and included in the licenses.html file using cargo-about.
- Source files will be formatted using
rustfmt, Prettier, and builtin hooks included with prek. - Links in Markdown source will be validated using lychee.
- Rust source will be linted using clippy (via the
cargo clippy-strictalias). - JavaScript source will be linted using ESLint.
- Rust source will be compiled using
cargo check.
Making a Release
The release process for all packages within the GWR workspace is handled by the Release-plz tool.
To start the release process, run:
release-plz release-pr
which will bump the version numbers of any updated packages and update the package CHANGELOG.md files as required. These changes will be automatically committed and a pull-request opened on Github for the proposed release to be reviewed.
Once the pull-request has been approved and merged the release process is completed by running:
release-plz release
which will tag the repo marking the correct commit with the versions for each
updated package, and automatically publishes the updated packages using
cargo publish and as Github releases.