diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..93302c18 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing to poethepoet + +So you'd like to contribute? Awesome! Here are some things worth knowing. + +## Reporting a bug / requesting a feature / asking a question + +Go [open an issue](https://github.com/nat-n/poethepoet/issues) and I'll probably reply soon. + +## 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 to it's particularly important for this project to benefit from diverse perspective 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. 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. + +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. + +4. Run `poetry install` to setup your development environment. ([install poetry](https://python-poetry.org/docs/#installation)) + +5. Do your code + +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. documentation in the form of a readme section. + +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. If you like to commit often, consider squashing your commits before continuing. + +7. Open a PR on GitHub. + +### 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. + +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 an 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. + +We like to keep a clean history, so squash-rebase merges are preferred for the _development_ or _main_ branches. + +### Overview of branches + +#### 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. + + +#### Working branches + +- **hotfix/** branches for minor/urgent bug fixes from main +- **feature/** branches for new feature development from development +- **bugfix/** for new bug fixes from development +- **doc/** branches for documentation changes + +### How to add a new feature + +1. Create your branch from _development_ + ``` + git fetch + git checkout origin/development + git checkout -b feature/my_new_feature + ``` +2. Create a pull request back to _development_ + +### How to add a hot fix + +1. Create your branch from _main_ + ``` + git fetch + git checkout origin/main + git checkout -b feature/my_new_feature + ``` +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 _release_ +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. diff --git a/README.rst b/README.rst index e06c8861..51f39e9a 100644 --- a/README.rst +++ b/README.rst @@ -407,14 +407,16 @@ Usage without poetry ==================== Poe the Poet was originally intended for use alongside poetry. But it works just as -well with any other kind of virtualenv, or no environment management at all. This behaviour is configurable via the :toml:`tool.poe.executor` global option (see above). +well with any other kind of virtualenv, or standalone. This behaviour is configurable via the :toml:`tool.poe.executor` global option (see above). By default poe will run tasks in the poetry managed environment, if the pyproject.toml contains a :toml:`tool.poetry` section. If it doesn't then poe looks for a virtualenv to use from :bash:`./.venv` or :bash:`./venv` relative to the pyproject.toml file. Otherwise it falls back to running tasks without any special environment management. Contributing ============ -There's plenty to do, come say hi in the issues! 👋 +There's plenty to do, come say hi in `the issues `_! 👋 + +Also check out the `CONTRIBUTING.MD `_ 🤓 TODO