Git(flow)¶
We use Git for version control and the project is hosted at Github. We use Gitflow (see also this description) for PyRigi development. In a nutshell, this means that there are two prominent branches in PyRigi’s Git repository:
main
, which contains the stable version of the packagedev
, which is used for the development.
Collaborators are not allowed to push their Git commits directly to these two branches. Rather, they should employ pull requests. Say Alice and Bob want to implement feature X in PyRigi. These are the tasks to be performed:
they branch from
dev
, creating a branch calledfeature-X
, and there they develop the intended functionality;once they are done, they push
feature-X
to GitHub and solicit a pull request offeature-X
intodev
;After creating a pull request, but before your code is merged into the
dev
branch, the code is checked by the maintainers, who may ask some other collaborator to serve as reviewer to ensure that the coding standards and other requirements are satisfied. In a review, Alice and Bob will get comments about specific pieces of code or other further suggestions. Once they think that they have adequately addressed a comment, Alica and Bob can use a tick in the GitHub GUI (:white_check_mark:
✅ or:heavy_check_mark:
✔️ ) to indicate that. If the reviewer agrees, they will resolve the comment.Once the pull request is approved, a maintainer merges
feature-X
intodev
and during the next version release cycle, it will be merged intomain
, making the code available through thepip
installation of PyRigi.
We propose a few categories for contributing branches:
features: branches to implement new features/improvements to the current status; their name should start by
feature-
documentation: branches to modify the documentation; their name should start by
doc-
, ordocfix-
when solving an errorbugs: branches to solve known bugs; their name should start by
bugfix-
hotfix: branches to solve an urgent error; their name should start by
hotfix-
testing: branches to add tests; their name should start by
test-
refactoring: branches to refactor the code; their name should start by
refactor-
When a bug is discovered on main
, the corresponding bugfix-
/hotfix-
branch should be created on main
.
Version Release¶
Once in a while, the maintainers merge the branch dev
into main
and create a new release.
The release numbers follow this scheme:
MAJOR version: significant functionality extensions yielding possibly incompatible API changes (x+1.y.z)
MINOR version: new functionality in a backward compatible manner (x.y+1.z)
PATCH version: backward compatible bug fixes (x.y.z+1).
To create a new MAJOR/MINOR version, the following steps should be taken by the maintainers:
Create a release branch
release-x.y.z
ondev
.Update the
version
andrelease
indoc/conf.py
and theversion
inpyproject.toml
.Update the
contributors.md
.Merge the branch into
dev
.Continue on the release branch and remove the files that are not supposed to be in the release (e.g.
poetry.lock
).Merge the branch into
main
.Check that the online documentation has been deployed correctly.
Add a new release tag in GitHub and generate the corresponding release notes.
Review the upload to PyPi.
Run
poetry update
and commitpoetry.lock
to update the dependencies ondev
.
To release a new PATCH version, the following should be taken using some steps from above:
Create a release branch
release-x.y.z
onmain
.Step 2. (and 3. if the patch involves a new contributor).
Steps 6.-10.
Create branch
release-x.y.z-main-to-dev
ondev
.Merge
main
intorelease-x.y.z-main-to-dev
while keeping thepoetry.lock
file fromrelease-x.y.z-main-to-dev
.Merge the branch
release-x.y.z-main-to-dev
via a PR todev
.