From 53f05d3cda7c1b99093624c533ac95c3a19dc0af Mon Sep 17 00:00:00 2001
From: Agustin Borgna <agustin.borgna@quantinuum.com>
Date: Fri, 20 Oct 2023 09:39:15 +0100
Subject: [PATCH] doc: Add DEVELOPMENT.md

---
 .github/pre-commit | 31 +++++++++++++++++
 DEVELOPMENT.md     | 86 ++++++++++++++++++++++++++++++++++++++++++++++
 README.md          |  4 +++
 3 files changed, 121 insertions(+)
 create mode 100755 .github/pre-commit
 create mode 100644 DEVELOPMENT.md

diff --git a/.github/pre-commit b/.github/pre-commit
new file mode 100755
index 0000000..d769356
--- /dev/null
+++ b/.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
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..2eac55b
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,86 @@
+# Welcome to the portgraph development guide <!-- omit in toc -->
+
+This guide is intended to help you get started with developing portgraph.
+
+If you find any errors or omissions in this document, please [open an issue](https://github.com/CQCL/portgraph/issues/new)!
+
+## #️⃣ Setting up the development environment
+
+You can setup the development environment 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.
+
+```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 portgraph
+
+We welcome contributions to portgraph! Please open [an issue](https://github.com/CQCL/portgraph/issues/new) or [pull request](https://github.com/CQCL/portgraph/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 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 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.
\ No newline at end of file
diff --git a/README.md b/README.md
index d85696f..8ae909d 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@ Please read the [API documentation here][].
 See [CHANGELOG][] for a list of changes. The minimum supported rust
 version will only change on major releases.
 
+## 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).