From eaba3351f14e7eb936ec89b23e9c8319a5db0542 Mon Sep 17 00:00:00 2001 From: Seyon Sivarajah Date: Fri, 22 Nov 2024 13:17:01 +0000 Subject: [PATCH] merge development.md --- DEVELOPMENT.md | 3 + hugr-llvm/DEVELOPMENT.md | 140 --------------------------------------- 2 files changed, 3 insertions(+), 140 deletions(-) delete mode 100644 hugr-llvm/DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 265d5dcb4..803f667ce 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -32,6 +32,9 @@ To setup the environment manually you will need: - Rust `>=1.75`: https://www.rust-lang.org/tools/install - uv `>=0.3`: docs.astral.sh/uv/getting-started/installation - capnproto `>=1.0`: https://capnproto.org/install.html +- Optional: llvm `== 14.0`. The "llvm" feature (backed by the sub-crate `hugr-llvm`) + requires LLVM installed. We use the rust bindings +[llvm-sys](https://crates.io/crates/llvm-sys) to [llvm](https://llvm.org/), Once you have these installed, you can install the required python dependencies and setup pre-commit hooks with: diff --git a/hugr-llvm/DEVELOPMENT.md b/hugr-llvm/DEVELOPMENT.md deleted file mode 100644 index b62d81654..000000000 --- a/hugr-llvm/DEVELOPMENT.md +++ /dev/null @@ -1,140 +0,0 @@ -# Welcome to the hugr-llvm development guide - -This guide is intended to help you get started with developing hugr-llvm. - -If you find any errors or omissions in this document, please [open an issue](https://github.com/CQCL/hugr-llvm/issues/new)! - -## #️⃣ Setting up the development environment - -You can set up the development environment in two ways: - -### The Nix way - -The easiest way to set up the development environment is to use the provided -[`devenv.nix`](devenv.nix) file. This will set up 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 set up the environment manually you will need: - -- Rust `>=1.75`: -- llvm `== 14.0`: we use the rust bindings -[llvm-sys](https://crates.io/crates/llvm-sys) to [llvm](https://llvm.org/), -- Poetry `>=1.8`: - -Once you have these installed, verify that your setup is working - -```bash -cargo test -``` - -## 💅 Coding Style - -We use `rustfmt` to enforce a consistent coding style. The CI will fail if the code is not formatted correctly. - -To format your code, run: - -```bash -cargo fmt -``` - -We also use various linters to catch common mistakes and enforce best practices. To run these, see [our CI config](./.github/workflows/ci-rs.yml). TODO Provide a better way, contributions welcome. - -## 📈 Code Coverage - -We run coverage checks on the CI. Once you submit a PR, you can review the -line-by-line coverage report on -[codecov](https://app.codecov.io/gh/CQCL/hugr-llvm/commits?branch=All%20branches). - -To run the coverage checks locally, first install `cargo-llvm-cov`. - -```bash -cargo install cargo-llvm-cov -``` - -Then run the tests, see [our CI config](/.github/workflows/ci-rs.yml). - -```bash -cargo llvm-cov --lcov --output-path lcov.info -``` - -This will generate a coverage file that can be opened with your favourite coverage viewer. In VSCode, you can use -[`coverage-gutters`](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters). - -## 🌐 Contributing to hugr-llvm - -We welcome contributions to hugr-llvm! Please open [an issue](https://github.com/CQCL/hugr-llvm/issues/new) or [pull request](https://github.com/CQCL/hugr-llvm/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. - -Some tests may be skipped based on the changes made. To run all the tests in -your PR mark it with a 'run-ci-checks' label and push new commits to it. - -The general format of a contribution title should be: - -``` -()!: -``` - -Where the scope is optional, and the `!` is only included 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 semicolons, 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. - -## :shipit: Releasing new versions - -We use automation to bump the version number and generate changelog entries -based on the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) labels. Release PRs are created automatically -for each package when new changes are merged into the `main` branch. Once the PR is -approved by someone in the [release team](.github/CODEOWNERS) and is merged, the new package -is published on PyPI or crates.io as appropriate. - -The changelog can be manually edited before merging the release PR. Note however -that modifying the diff before other changes are merged will cause the -automation to close the release PR and create a new one to avoid conflicts. - -### Rust crate release - -Rust releases are managed by `release-plz`. This tool will automatically detect -breaking changes even when they are not marked as such in the commit message, -and bump the version accordingly. - -To modify the version being released, update the `Cargo.toml`, -`CHANGELOG.md`, PR name, and PR description in the release PR with the desired version. You may also have to update the dates. -Rust pre-release versions should be formatted as `0.1.0-alpha.1` (or `-beta`, or `-rc`). - -### Patch releases - -Sometimes we need to release a patch version to fix a critical bug, but we don't want -to include all the changes that have been merged into the main branch. In this case, -you can create a new branch from the latest release tag and cherry-pick the commits -you want to include in the patch release. - -You will need to modify the version and changelog manually in this case. Check -the existing release PRs for examples on how to do this. Once the branch is -ready, create a [github release](https://github.com/CQCL/hugr-llvm/releases/new). -The tag should follow the format used in the previous releases, e.g. `hugr-llvm-v0.1.1`. - -For rust crates, you will need someone from the release team to manually -publish the new version to crates.io by running `cargo release`.