Skip to content

Latest commit

 

History

History
184 lines (140 loc) · 5.78 KB

CONTRIBUTING.md

File metadata and controls

184 lines (140 loc) · 5.78 KB
Raw

Development

Prerequisites

Setup

  1. Create a virtual environment and install the dev dependencies with

     pip install -r requirements/dev.txt

  2. Install the pre-commit hooks with

     pre-commit install

    This will mainly make sure you can't commit if your code is not linted with black. The pre-commit hook will check if your code is linted and if it is not it will simply lint it for you, you then only need to stage the changes made by the linter and commit again, as simple as that :)

Philosophy

Development of a feature for this repository should follow the workflow described by Vincent Driessen.

Here are the minimal procedure you should follow :

Step 1: Describe the issue on github

Create an issue on the github repository, describing the problem you will then address with your feature/fix. This is an important step as it forces one to think about the issue (to describe an issue to others, one has to think it through first).

Step 2: Solve the issue locally

  1. Create a separate branch from dev, to work on

    git checkout -b feature/myfeature dev

    The convention is to always have feature/ in the branch name. The myfeature part should describe shortly what the feature is about (separate words with -). If you are fixing and error you can replace feature/ by fix/.

  2. Try to follow these conventions for commit messages:

    • Keep the subject line short (i.e. do not commit more than a few changes at the time)
    • Use imperative for commit messages
    • Do not end the commit message with a period You can use 
      git commit --amend
      to edit the commit message of your latest commit (provided it is not already pushed on the remote server). With --amend you can even add/modify changes to the commit.

  3. Push your local branch on the remote server origin

    git push

    If your branch does not exist on the remote server yet, git will provide you with instructions, simply follow them.

Step 3: Run tests locally

To run tests locally, install the dependencies

pip install -r tests/test_requirements.txt
  1. Integration/unit tests 
    pytest tests
  2. Linting tests 
    flake8
    and 
    pylint
    You can fix the linting errors either manually or with the packages autopep8 or black for example.

Step 4: Submit a pull request (PR)

Follow the steps of the github help to create the PR. Please note that you PR should be directed from your branch (for example myfeature) towards the branch dev.

Add a line Fix #<number of the issue created in Step 2.0> in the description of your PR, so that when it is merged, it automatically closes the issue once your code gets merged into the default branch of your repository. Here is a list of other keywords you can use to automatically close the issues

Step 5: Setup continuous integration

To have the test run automatically everytime you push to a pull request you can add the bash commands under # command to run tests of the .travis.yml file. For this you need to have an account by Travis and link your repo to their service. Soon GitHub action might take care of this directly within github.

In the .travis.yml file are many options commented out, you can have very complexe schemes to test on many different python versions etc. For more information look at Travis doc for python.

Release protocol

Once you are ready to publish a release, branch off from dev bash git checkout -b release/vX.Y.Z dev For meaning of X, Y and Z version numbers, please refer to this semantic versioning guidelines.

In this branch, you should normally only update the version number in the CHANGELOG.md and setup.py files.

Your CHANGELOG.md file could look like this before the release

## [unreleased]

### Added
- feature 1
- feature 2
### Changed
- thing 1
- thing 2
### Removed
- some stuff

Simply replace unreleased by X.Y.Z and add the date of release in ISO format, then add the structure for a new unreleased version

## [unreleased]

### Added
-
### Changed
-
### Removed
-

## [X.Y.Z] - 20**-**-**
### Added
- feature 1
- feature 2
### Changed
- thing 1
- thing 2
### Removed
- some stuff

After pushing these changes, create a pull request from release/vX.Y.Z towards master and merge it in master.

Locally, merge release/vX.Y.Z into dev

git checkout release/vX.Y.Z

git pull

git checkout dev

git merge release/vX.Y.Z

And push your these updates to the remote

git push

The idea behind this procedure is to avoid creating a merge commit in dev (because master would otherwise have two merge commit for this release once you merge the next release).

Finally, create a release on github. Please choose master as the target for the tag and format the tag as vX.Y.Z. In the description field simply copy-paste the content of the CHANGELOGdescriptions for this release and you're done!