Contributing¶
Here we explain how to contribute to a project that adopted this template. Actually, you can use this same scheme when contributing to this template.
Fork this repository¶
Fork this repository before contributing. It is a better practice, possibly even enforced, that only Pull Request from forks are accepted. In my opinion this creates a cleaner representation of the whole contributions to the project.
Install for developers¶
First, clone the repository as described in the section above.
Create a dedicated Python environment where to develop the project.
If you are using pip follow the official instructions on Installing packages using pip and virtual environments, most likely what you want is:
python3 -m venv pyprojskel
source pyprojskel/bin/activate
If you are using Anaconda go for:
conda create --name pyprojskel python=3.7
conda activate pyprojskel
Where pyprojskel is the name you wish to give to the environment dedicated to this project.
Either under pip or conda, install the package in develop mode, and also tox.
python setup.py develop
# for pip
pip install tox bumpversion
# for conda
conda install tox bumpversion -c conda-forge
Under this configuration the source you edit in the repository git folder is automatically reflected in the development installation.
Continue your implementation following the development guidelines described bellow.
Branch workflow¶
The following applies to external contributors, yet main developers can also follow these guidelines.
Branch workflow for development and contribution should follow the Gitflow Workflow guidelines. Please read careful through that guide. Here we highlight the general approach with some tasteful additions such as the --no-ff flag.
Clone your fork¶
Indeed the first thing to do is to clone your fork, and keep it up to date with the upstream:
git clone https://github.com/YOUR-USERNAME/python-project-skeleton.git
cd into/cloned/fork-repo
git remote add upstream git://github.com/joaomcteixeira/python-project-skeleton.git
git fetch upstream
git pull upstream latest
New feature¶
To work on a new feature, branch out from the latest branch:
git checkout latest
git checkout -b feature_branch
Develop the feature and keep regular pushes to your fork with comprehensible commit messages.
Push to latest¶
To see your development accepted in the main project, you should create a Pull Request to the latest branch following the PULLREQUEST.rst guidelines.
Before submitting a Pull Request, verify your development branch passes all tests as described bellow . If you are developing new code you should also implement new test cases.
If you are an official contributor to this repository, have write permissions, and are sure the new feature branch passes tests, directly merge to the latest branch.
You should bump a patch beforehand.
# on your feature_branch
bumpversion patch --no-tag
git push origin feature_branch
git checkout latest
git merge --no-ff feature_branch
git push origin latest
The --no-ff option avoids Fastforward merging (1, 2), keeping a record of the branching out/in history.
To official contributors¶
Release Branches¶
Create a short lived branch to prepare for the release candidate, in this example release/0.1.0.
git checkout latest
git checkout -b release/0.1.0
Fix the final bugs, docs and minor corrections, and finally bump the version.
# first commit and push your changes
# then bump
bumpversion patch|minor|major
git push origin release/0.1.0
Finally, merge to master AND from master to latest.
git checkout master
git merge --no-ff release/0.1.0
git push origin master --tags
git checkout latest
git merge --no-ff master
Hotfixes from master¶
The hotfix strategy is applied when a bug is identified in the production version that can be easily fixed.
git checkout master
git checkout -b hotfix_branch
Work on the fix…
# push yours commits to GitHub beforehand
git push origin hotfix_branch
bumpversion patch
git push origin hotfix_branch --tags
git checkout master
git merge --no-ff hotfix_branch
git push origin master
git checkout latest
git merge --no-ff master
git push origin latest
Uniformed Tests¶
Thanks to Tox we can have a uniform testing platform where all developers are forced to follow the same rules and, above all, all tests occur in a controlled Python environment.
With Tox, the testing setup can be defined in a configuration file, the tox.ini, which contains all the operations that are performed during the test phase. Therefore, to run the unified test suite, developers just need to execute tox, provided tox is installed in the Python environment in use.
pip install tox
# or
conda install tox -c conda-forge
Todo
Review and consider integrating using tox to setup development envs -> https://tox.readthedocs.io/en/latest/example/devenv.html
One of the greatest advantages of using Tox together with the src layout, aside from uniforming the testing routines across developers, is that tests scripts actually perform against an installed source (our package) inside an isolated deployment environment. In order words, tests are performed in an environment simulating a post-deployment state instead of a pre-deploy/development environment. Under this setup, there is no need, in general cases, to deploy test scripts along with the actual source, in my honest opinion - see MANIFEST.in.
Todo
Discuss the need to deploy test scripts.
Before creating a Pull Request from your branch, certify that all the tests pass correctly by running:
tox
These are exactly the same tests that will be performed in the CI Platforms.
Also, you can run individual environments if you wish to test only specific functionalities, for example:
tox -e check # code style and file compatibility
tox -e spell # spell checks documentation
tox -e docs # only builds the documentation
Bumpversion¶
I found two main version string handlers around: bumpversion and versioneer. I chose bumpversion for this repository template. Why? I have no argument against versioneer or others, simply I found bumpversion to be so simple, effective and configurable that I could only adopt it. Congratulations to both projects nonetheless.