-

Contributing#

+

Contributing

So you’d like to contribute? Awesome! Here are some things worth knowing.

-

Reporting a bug / requesting a feature / asking a question#

+

Reporting a bug / requesting a feature / asking a question

Go open an issue or start a discussion and I’ll probably reply soon.

-

Contributing to the docs#

+

Contributing to the docs

Just make a PR with your proposed changes targeting the main branch. The documentation website will update once your PR is merged.

-

Contributing code#

+

Contributing code

-

Preface#

+

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.

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#

+

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. @@ -281,28 +281,28 @@

    Development process -

    Pull requests#

    +

    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 and docs are there.

-

Branching model#

+

Branching model

This project implements something like git flow.

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.

-

Overview of branches#

+

Overview of branches

-

Historic 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#

+

Working branches

  • hotfix/ branches for minor/urgent bug fixes from main

  • feature/ branches for new feature development from development

    • @@ -312,7 +312,7 @@

    Working branches -

    How to add a new feature#

    +

    How to add a new feature

    1. Create your branch from development

    @@ -326,7 +326,7 @@

    How to add a new feature -

    How to add a hot fix#

    +

    How to add a hot fix

    1. Create your branch from main

    @@ -340,7 +340,7 @@

    How to add a hot fix

-

How to create release#

+

How to create 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 (use the Generate release notes button as a starting point), and the GitHub CI will do the rest.

    3. @@ -428,12 +428,12 @@

    How to create release - - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + + - - - - - + + + + + +