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

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

Finally the Git hooks need to be installed within the cloned copy of the GWR repo:

prek install

Branching the Repo

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. Long running or collaborative development will likely benefit from having the branch pushed to the origin well in advance of when a pull request may be opened, and doing so will cause the CI workflows to be run on every commit.

For short lived branches pushed only at the point of opening a pull request the branch naming prefix pr- should be used, for example, pr-new-example-app. Branches named with this prefix will still cause the pull request specific CI workflow to run, but will avoid the push specific CI workflow from running until the point they are merged.

Committing a Change

All commits made to the GWR repo must follow the Conventional Commits 1.0.0 specification. This allows the automatic generation of both a top-level changelog covering the whole workspace as well as an individual changelog for each package within the workspace.

When writing a commmit message in this form:

• The set of types that should generally be used can be found in the commit_parsers array within the release-plz.toml configuration file. This array also details the sections each type will be included in within the changelog.

• The optional scope should be used to detail the name of the updated package. For example:

  fix(gwr-developer-guide): check for panic when running mdBook tests
  

  • If the change applied to multiple, but not all packages, the names should be comma seperated. For example:

    feat(gwr-track,gwr-spotter): capnp binary file support
    

  • If the change applies to all Rust packages, infrastructure, CI, or general configuration the scope can be omitted. For example:

    docs: add example use for all public APIs
    

    infra: set default pre-commit hooks to install
    

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