Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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-strict alias).
  • 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.