Development Guidelines¶
There are some rules in how PyR3 should be developed, related to git branch structure, testing and building. We will make an attempt to describe them here.
Git repo management¶
In general this project is making use of a successfull Git branching model With partial automation with python scripts and some changes.
main
and develop
¶
In repo there are two branches that lives next to each other.
The develop
branch contains all in-development code with all
unstable features and changes.
On the other hand main
branch always contains most recent stable
code.
Feature branches¶
Feature branches always follows following naming convention with “feature-” prefix and unique feature name postfix. eg. “feature-generators”, “feature-linux-support”
Also, those branches are always created from develop
branch and they
merge back into develop
.
To be sure you wont mess anything in feature branch creation you can use python script available in this repo in scripts/fork_feature.py:
python -m scripts.fork_feature <feature-name>
“feature-” prefix is automatically added so you don’t have to include in script call args.
After you finish working on your feature open a pull request on GitHub and either wait for request being accepted or if you have necessary rights, merge it yourself. Don’t use scripts/merge_feature.py anymore, pull requests are better way of managing branch merging in this case.
Release branches (major and minor)¶
After adding a bunch of features to develop
, make sure you have
described them in CHANGELOG.rst
on develop
branch. Make sure
version tag above feature description matches version tag you are
planning to use for this release.
Release branch have to be drafted from develop
and you should use
scripts/fork_release.py
for it unless you are willing to fix all the
messed up version tags. Im sure you don’t, so never create release
branch manually via git.
python -m scripts.fork_release --major
or
python -m scripts.fork_release --minor
Using –patch is highly discouraged, for small changes us hotfix approach.
After you make sure release branch is release ready go to GitHub and
create pull request to merge release-x.y.z
into main
. It will
run bunch of tests. You should wait for tests to succeed.
Then, If you have enough permissions, you can accept merge.
Merge will cause additional merges to run to sync remote branches, so
after release you have to locally pull changes to both main
and
develop
. It will also automatically create release with release
notes from CHANGELOG.rst
file.
PyPI release is not automatically created.
Hotfix branches (patch)¶
Hotfix branches are used to hotfix already existing releases. Therefore
they are forked from release branch patch corresponds to. Make sure you
use scripts/fork_hotfix.py
to create hotfix branch, as all version
tags have to be updated, and for sure you don’t want to do it manually.
python -m scripts.fork_hotfix <version-tag-to-fork-from>
eg.
python -m scripts.fork_hotfix v0.3.0
To merge this branch do the same as with release branch (see Release branches (major and minor)).