ci: Start checking conventional commit titles

.github/pre-commit

@@ -0,0 +1,31 @@
+#!/bin/sh
+
+# A pre-push hook for rust codebases that checks formatting, clippy, and tests
+
+set -eu
+
+if [[ "${IGNORE_RUSTHOOKS:=0}" -ne 0 ]]; then
+    echo "Ignoring rusthooks"
+    exit 0
+fi
+
+if ! cargo fmt -- --check
+then
+    echo "There are some code style issues."
+    echo "Run cargo fmt first."
+    exit 1
+fi
+
+if ! cargo clippy --all-targets --all-features --workspace -- -D warnings
+then
+    echo "There are some clippy issues."
+    exit 1
+fi
+
+if ! cargo test --all-features
+then
+    echo "There are some test issues."
+    exit 1
+fi
+
+exit 0

.github/workflows/pr-title.yml

@@ -0,0 +1,72 @@
+name: Check Conventional Commits format
+
+on:
+  pull_request_target:
+    branches:
+      - main 
+    types:
+      - opened
+      - edited
+      - synchronize
+      - labeled
+      - unlabeled
+  merge_group:
+    types: [checks_requested]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  main:
+    name: Validate Conventional Commit PR title
+    runs-on: ubuntu-latest
+    # The action does not support running on merge_group events,
+    # but if the check succeeds in the PR there is no need to check it again.
+    if: github.event_name == 'pull_request_target'
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Configure which types are allowed (newline-delimited).
+          # Default: https://github.com/commitizen/conventional-commit-types
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            ci
+            chore
+            revert
+          # Configure which scopes are allowed (newline-delimited).
+          # These are regex patterns auto-wrapped in `^ $`.
+          #scopes: |
+          #  .*
+          # Configure that a scope must always be provided.
+          requireScope: false
+          # Configure which scopes are disallowed in PR titles (newline-delimited).
+          # For instance by setting the value below, `chore(release): ...` (lowercase)
+          # and `ci(e2e,release): ...` (unknown scope) will be rejected.
+          # These are regex patterns auto-wrapped in `^ $`.
+          #disallowScopes: |
+          #  release
+          #  [A-Z]+
+          # Configure additional validation for the subject based on a regex.
+          # This example ensures the subject doesn't start with an uppercase character.
+          #subjectPattern: ^(?![A-Z]).+$
+          # If `subjectPattern` is configured, you can use this property to override
+          # the default error message that is shown when the pattern doesn't match.
+          # The variables `subject` and `title` can be used within the message.
+          #subjectPatternError: |
+          #  The subject "{subject}" found in the pull request title "{title}"
+          #  didn't match the configured pattern. Please ensure that the subject
+          #  doesn't start with an uppercase character.
+          # If the PR contains one of these newline-delimited labels, the
+          # validation is skipped. If you want to rerun the validation when
+          # labels change, you might want to use the `labeled` and `unlabeled`
+          # event triggers in your workflow.
+          ignoreLabels: |
+            ignore-semantic-pull-request

DEVELOPMENT.md

@@ -0,0 +1,107 @@
+# Welcome to the HUGR development guide <!-- omit in toc -->
+
+This guide is intended to help you get started with developing HUGR.
+
+If you find any errors or omissions in this document, please [open an issue](https://github.com/CQCL/hugr/issues/new)!
+
+## #️⃣ Setting up the development environment
+
+You can setup the development environment in two ways:
+
+### The Nix way
+
+The easiest way to setup the development environment is to use the provided
+[`devenv.nix`](devenv.nix) file. This will setup a development shell with all the
+required dependencies.
+
+To use this, you will need to install [devenv](https://devenv.sh/getting-started/).
+Once you have it running, open a shell with:
+
+```bash
+devenv shell
+```
+
+All the required dependencies should be available. You can automate loading the
+shell by setting up [direnv](https://devenv.sh/automatic-shell-activation/).
+
+### Manual setup
+
+To setup the environment manually you will need:
+
+- Rust: https://www.rust-lang.org/tools/install
+
+You can use the git hook in [`.github/pre-commit`](.github/pre-commit) to automatically run the test and check formatting before committing.
+To install it, run:
+
+```bash
+ln -s .github/pre-commit .git/hooks/pre-commit
+# Or, to check before pushing instead
+ln -s .github/pre-commit .git/hooks/pre-push
+```
+
+## 🏃 Running the tests
+
+To compile and test the rust code, run:
+
+```bash
+cargo build
+cargo test
+```
+
+Run the benchmarks with:
+
+```bash
+cargo bench
+```
+
+Finally, if you have rust nightly installed, you can run `miri` to detect
+undefined behaviour in the code. Note that the _devenv_ shell only has rust
+stable available.
+
+```bash
+cargo +nightly miri test
+```
+
+## 💅 Coding Style
+
+The rustfmt tool is used to enforce a consistent rust coding style. The CI will fail if the code is not formatted correctly.
+
+To format your code, run:
+
+```bash
+# Format rust code
+cargo fmt
+```
+
+We also check for clippy warnings, which are a set of linting rules for rust. To run clippy, run:
+
+```bash
+cargo clippy --all-targets
+```
+
+## 🌐 Contributing to HUGR
+
+We welcome contributions to HUGR! Please open [an issue](https://github.com/CQCL/hugr/issues/new) or [pull request](https://github.com/CQCL/hugr/compare) if you have any questions or suggestions.
+
+PRs should be made against the `main` branch, and should pass all CI checks before being merged. This includes using the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) format for the PR title.
+
+The general format of a contribution title should be:
+
+```
+<type>(<scope>)!: <description>
+```
+
+Where the scope is optional, and the `!` is only includes if this is a semver breaking change that requires a major version bump.
+
+We accept the following contribution types:
+
+- feat: New features.
+- fix: Bug fixes.
+- docs: Improvements to the documentation.
+- style: Formatting, missing semi colons, etc; no code change.
+- refactor: Refactoring code without changing behaviour.
+- perf: Code refactoring focused on improving performance.
+- test: Adding missing tests, refactoring tests; no production code change.
+- ci: CI related changes. These changes are not published in the changelog.
+- chore: Updating build tasks, package manager configs, etc. These changes are not published in the changelog..
+- revert: Reverting previous commits.

README.md

@@ -11,7 +11,7 @@ ecosystem.
 It provides a high-fidelity representation of operations, that facilitates
 compilation and encodes runnable programs.
 
-The HUGR specification (still in draft) is [here](specification/hugr.md).
+The HUGR specification is [here](specification/hugr.md).
 
 ## Features
 
@@ -28,6 +28,10 @@ quantinuum-hugr = "0.1"
 
 The library crate is called `hugr`.
 
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for instructions on setting up the development environment.
+
 ## License
 
 This project is licensed under Apache License, Version 2.0 ([LICENSE][] or http://www.apache.org/licenses/LICENSE-2.0).