Development Guidelines

Best practices in FOSS development

• It is agreed that the development guidelines should remain very simple. The typical contribution workflow is to start a branch from the current master (in a fork for external developers) and the pull request is also made to master.
• New features must have documentation and tests. Some PEP8 requirements (with exceptions, which are described by project) must be followed.
• A need for a tutorial or template on how to properly log events inside a WPS and how to write WPS tests is identified.
• The release cycle for birdhouse is roughly 2-3 months, coinciding with the video conference meetings.
• There is a suggestion to clean up repositories that have a lot of obsolete branches. Deleted branches still maintain their commits in the history if they were merged at some point.
• It is strongly suggested that before creating a feature branch to work on, there should be an issue created to explain & track what is being done for that feature.

Contribute Code

My personal workflow

• I keep the master branch of my fork in sync with the upstream repo (master is a mirror of upstream/master).

$ git remote -v  # check available remotes and add one if needed
upstream
$ git checkout master
$ git fetch upstream master
$ git merge upstream/master
$ git push

• I'm using dev branches for my developments.

$ git checkout pingudev
# here I'm free to do what I like ...

• I'm using issue branches to provide pull-requests. Usually they are created from master with a squash-merge from a dev branch:

$ git checkout master
$ git checkout -b issue-7-fix-docu
$ git merge --squash pingudev
$ git push

When the pull request is merged I can safely remove the issue branch:

$ git branch -D issue-7-fix-docu
$ git fetch -p
# and sync master like above to get the PR into your local fork.

... and I like to reset my dev branch:

$ git checkout pingudev
$ git reset --hard master
$ git push -f

The formal way

The formal way to contribute code is recommended for stable/productive code repositories which have two or more developers:

• Choose the GitHub repository where you want to contribute.
• Open an issue on GitHub at this repository, lets say you have issue number 7.
• Either fork the repository or add your personal development branch if you have the access rights.
• When your contribution is ready open an issue branch with a name like issue-7-short-descrption.
• Merge the code with parts you want to contribute to this issue branch. It should not have to many commits. You may use git-cherrypick to select commits or git-merge-squash to reduce all commits to a single one.
• Provide a pull-request (PR) with a reference to your ticket.
• Ask for review.
• When the review process has finished the PR will be merged. By using fix #7 in the merge comment the issue gets closed automatically.
• Thanks :)

Release Cycle

Links

• PyWPS Developers Guide