diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index ea7c20e0..8f81e572 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -4,16 +4,12 @@ knowing. Reporting a bug / requesting a feature / asking a question ---------------------------------------------------------- -Go `open an issue `_ or -`start a discussion `_ and -I’ll probably reply soon. +Go `open an issue `_ or `start a discussion `_ and I’ll probably reply soon. Contributing to the docs ------------------------ -Just make a PR with your proposed changes targeting the main branch. -The [documentation website](https://poethepoet.natn.io/) will update once your -PR is merged. +Just make a PR with your proposed changes targeting the main branch. The `documentation website `_ will update once your PR is merged. Contributing code ----------------- @@ -21,72 +17,54 @@ Contributing code Preface ~~~~~~~ -If you’re willing to contribute your ideas and effort to making poethepoet -better, then that’s awesome and I’m grateful. I don’t have all the answers so -it’s particularly important for this project to benefit from diverse -perspectives and technical expertise. +If you’re willing to contribute your ideas and effort to making poethepoet better, then that’s awesome and I’m grateful. I don’t have all the answers so it’s particularly important for this project to benefit from diverse perspectives and technical expertise. -However please be aware that a lot of thought has gone into the architecture of -poethepoet, and whilst I know it’s not perfect, and I am very interested in -alternative perspectives, I do have strong (and I hope reasonable) opinions -about how certain things should work. This particularly applies to naming and -internal APIs. There is a lot to consider in terms of making sure the tool stays -simple, flexible, and performant. So please don’t be offended if there is some -push back. +However please be aware that a lot of thought has gone into the architecture of poethepoet, and whilst I know it’s not perfect, and I am very interested in alternative perspectives, I do have strong (and I hope reasonable) opinions about how certain things should work. This particularly applies to naming and internal APIs. There is a lot to consider in terms of making sure the tool stays simple, flexible, and performant. So please don’t be offended if there is some push back. Development process ~~~~~~~~~~~~~~~~~~~ -1. If your planned changes entail non-trivial UI or internal API changes then - it’s a good idea to bring them up for discussion as a - `GitHub issue `_ first. +1. If your planned changes entail non-trivial UI or internal API changes then it’s a good idea to bring them up for discussion as a `GitHub issue `_ first. -2. Fork and clone the repo, and create a feature or bugfix branch off of the - *development* branch. +2. Fork and clone the repo, and create a feature or bugfix branch off of the *development* branch. -3. Double check that you’re starting from the *development* branch, and not from - the the *main* branch. +3. Double check that you’re starting from the *development* branch, and not from the the *main* branch. -4. Run ``poetry install`` to setup your development environment. - (`install poetry `__) +4. Run ``poetry install`` to setup your development environment. (`install poetry `__) 5. Do your code. -6. If you’ve added a feature then before it can be including in a release we - will need: +6. If you’ve added a feature then before it can be including in a release we will need: a. a feature test along the same lines as the examples in the tests dir, b. to update documentation. -5. Run ``poe check`` to check that you haven’t broken anything that will - block the CI pipeline. +5. Run ``poe check`` to check that you haven’t broken anything that will block the CI pipeline. -6. Create a commit with a clear commit message that describes the commit - contents. +6. Create a commit with a clear commit message that describes the commit contents. 7. Open a PR on GitHub. +.. seealso:: + + You can also open a draft PR proposing incomplete changes to recieve feedback. + Pull requests ~~~~~~~~~~~~~ -There isn’t currently a pull request template, but please try and be descriptive -about what problem you’re solving and how, and reference related issues. +There isn’t currently a pull request template, but please try and be descriptive about what problem you’re solving and how, and reference related issues. -In some cases it might be acceptable to merge code to *development* to make a -pre-release from it without including full automated tests and documentation. -However this is a special case, because it blocks further releases from the -*development* branch until the tests and docs are there. +In some cases it might be acceptable to merge code to *development* to make a pre-release from it without including full automated tests and documentation. +However this is a special case, because it blocks further releases from the *development* branch until the tests and docs are there. Branching model ~~~~~~~~~~~~~~~ This project implements something like git flow. -*TL;DR* branch off of *development* for new features, or *main* for minor bug -fixes or doc improvements. +*TL;DR* branch off of *development* for new features, or *main* for documentation improvements. -We like to keep a clean history, so squash-rebase merges are preferred for the -*development* or *main* branches. +We like to keep a clean history, so squash-rebase merges are preferred for the *development* or *main* branches. Overview of branches ~~~~~~~~~~~~~~~~~~~~ @@ -95,8 +73,7 @@ Historic branches ^^^^^^^^^^^^^^^^^ - **main** the primary branch containing released code and up to date docs. -- **development** in progress and pre-released features that are expected to be - included in a release when ready. +- **development** in progress and pre-released features that are expected to be included in a release when ready. Working branches ^^^^^^^^^^^^^^^^ @@ -132,23 +109,9 @@ How to add a hot fix 2. Create a pull request back to *main*, and one to *development* -How to create pre-release -~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. From the head of the *development* branch, create release commit that - bumps the version in ``pyproject.toml`` and ``__version__.py`` - (there’s a test to ensure these are in sync). -2. Create a release (and tag) on GitHub, following the existing - convention for naming and release notes format, and the GitHub CI - will do the rest. - How to create release ~~~~~~~~~~~~~~~~~~~~~ -1. Create a branch off of *development* like **release/1.0.0** and add a - commit to bump the version in ``pyproject.toml`` and - ``__version__.py``. -2. Merge it into both *main* and *development* -3. Create a GitHub release from the head of main, following the existing - convention for naming and release notes format, and the GitHub CI - will do the rest. +1. From the head of the *development* branch, create release commit that bumps the version in ``pyproject.toml`` and ``__version__.py`` (there’s a test to ensure these are in sync). +2. Create a release (and tag) on GitHub, following the existing convention for naming and release notes format (use the *Generate release notes* button as a starting point), and the GitHub CI will do the rest. +3. Unless it is a pre-release then the final step is to merge *development* into *main*. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..c6203e49 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,10 @@ +## Description of changes + +Replace this text with a description of the changes proposed in this PR, including the motivation for these changes and a reference to any related GitHub issue or discussion. + +## Pre-merge Checklist + +- [ ] New features (if any) are covered by new feature tests +- [ ] New features (if any) are documented +- [ ] `poe check` executed successfully +- [ ] PR targets the *development* branch for code changes or *main* if only documentation is updated