From 49401bf71a491a01cf298695a6e229c050ed1b8b Mon Sep 17 00:00:00 2001 From: James Robinson Date: Thu, 29 Aug 2024 16:01:57 +0100 Subject: [PATCH] :truck: Move docs instructions to CONTRIBUTING.md --- CONTRIBUTING.md | 67 ++++++++++++++++++++++++++++++++++++------------- docs/README.md | 44 -------------------------------- 2 files changed, 49 insertions(+), 62 deletions(-) delete mode 100644 docs/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 060921fd47..97d316ed67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ The most pertinent features of the DevOps methodology for this project are: - **automation**: maximal automation is the primary goal - **quality**: full integration testing each time features are added -### Project workflow +## Project workflow Although we are not following an Agile workflow, we still think that the following features are important: @@ -70,11 +70,19 @@ This means that: - checking out the `latest` branch, will give you the latest tagged release - the `develop` branch, which is the default branch of the repository, contains the latest cutting-edge code that has not yet made it into a release -- releases are made by branching from `develop` into a branch called `release-` - - deployment is tested from this release and any necessary integration changes are made on this branch - - the branch is then merged into `latest` (which is tagged) as the next release **and** into `develop` so that any fixes are included there - we prefer to use [merge commits](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github) in order to avoid rewriting the git history +### Issues as conversations + +If you have an idea for a piece of work to complete, please **open an issue**. + +The name `issue` comes from a concept of catching errors (bugs :bug:) in software, but for this project they are simply our **tasks**. +If an issue is growing to encompass more than one task, consider breaking it into multiple issues. + +You can think of the issues as **conversations** about a particular topic. +`GitHub`'s tagline is **social coding** and the issues are inspired by social media conversations. +Alternatively (and this is encouraged) you can use the issue to keep track of where you're up to with the task and add information about next steps and barriers. + ### Discussions vs Issues **Discussions** are the best place for informal talk about the project @@ -106,16 +114,7 @@ Each issue should be assigned to an appropriate [milestone](https://github.com/a If you have been assigned an issue, please be ready to explain in the [project meeting](#project-meetings) what your progress has been. In a perfect world you'll have completed the task, documented everything you need to and we'll be able to **close** the issue (to mark it as complete). -### Issues as conversations - -If you have an idea for a piece of work to complete, please **open an issue**. - -The name `issue` comes from a concept of catching errors (bugs :bug:) in software, but for this project they are simply our **tasks**. -If an issue is growing to encompass more than one task, consider breaking it into multiple issues. - -You can think of the issues as **conversations** about a particular topic. -`GitHub`'s tagline is **social coding** and the issues are inspired by social media conversations. -Alternatively (and this is encouraged) you can use the issue to keep track of where you're up to with the task and add information about next steps and barriers. +## Contributing your changes ### Making a change with a pull request @@ -128,12 +127,44 @@ To contribute to the codebase you'll need to: ### Making a change to the documentation The docs, including for older releases, are available [here](https://data-safe-haven.readthedocs.io). - You should follow the same instructions as above to [make a change with a pull request](#making-a-change-with-a-pull-request) when editing the documentation. -To preview your changes, you can build the docs locally. See [docs/README.md](docs/README.md). +The documentation is built from Markdown files using [Sphinx](https://www.sphinx-doc.org/) and [MyST parser](https://myst-parser.readthedocs.io/). +To preview your changes, you can build the docs locally with `hatch`: + +```console +> hatch run docs:build +``` + +- The generated documents will be placed under `build/html/`. +- To view the documents open `build/html/index.html` in your browser, for example: + +```console +> firefox build/html/index.html +``` + +## Preparing a new release + +Releases are made by branching from `develop` into a branch called `release-` + +- deployment is tested from this release and any necessary integration changes are made on this branch +- the branch is then merged into `latest` (which is tagged) as the next release **and** into `develop` so that any fixes are included there + +The release can then be published to PyPI: + +- Build the tarball and wheel + +```console +> hatch run build +``` + +- Upload to PyPI, providing your API token at the prompt + +```console +$ hatch run publish --user __token__ +``` -### Who's involved in the project +## Who's involved in the project Take a look at the full list of contributors on our [README](README.md). @@ -149,7 +180,7 @@ To add new contributor to the README table, see the [all-contributors CLI docume You can get in touch with the development team at safehavendevs@turing.ac.uk. -## Thank you! +**Thank you!** You're awesome! :wave::smiley: diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 3b98ee18e3..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# Documentation - -The documentation is built from Markdown files using [Sphinx](https://www.sphinx-doc.org/) and [MyST parser](https://myst-parser.readthedocs.io/). - -## Requirements - -Install the following requirements before starting - -- [Hatch](https://hatch.pypa.io/1.9/install/) - -## Building the Documentation - -Build the documentation with `hatch`. - -:::{code} bash -$ hatch run docs:build -::: - -The generated documents will be placed under `build/html/`. -To view the documents open `build/html/index.html` in your browser. -For example - -:::{code} bash -$ firefox build/html/index.html -::: - -## Publishing a new release to PyPI - -- Build the tarball and wheel - -:::{code} bash -$ hatch run build -::: - -- Upload to PyPI, providing your API token at the prompt - -:::{code} bash -$ hatch run publish --user __token__ -::: - -## Reproducible Builds - -We use [`pip-compile`](https://pip-tools.readthedocs.io/en/latest/) behind the scenes to ensure that each commit uses the same set of packages to build the documentation. -This means that each build is fully reproducible.