Developers Guide¶
If you identify a bug in the PyWPS code base and want to fix it, if you would like to add further functionality, or if you wish to expand the documentation, you are welcomed to contribute such changes. However, contributions to the code base must follow an orderly process, described below. This facilitates both the work on your contribution as its review.
0. GitHub account¶
The PyWPS source code is hosted at GitHub, therefore you need an account to contribute. If you do not have one, you can follow these instructions.
1. Open a new issue¶
The first action to take is to clearly identify the goal of your contribution. Be it a bug fix, a new feature or documentation, a clear record must be left for future tracking. This is made by opening an issue at the GitHub issue tracker. In this new issue you should identify not only the subject or goal, but also a draft of the changes you expect to achieve. For example:
Title: Process class must be magic
Description: The Process class must start performing some magics. Give it a magic wand.
2. Fork and clone the PyWPS repository¶
When you start modifying the code, there is always the possibility for something to go wrong, rendering PyWPS unusable. The first action to avoid such a situation is to create a development sand box. In GitHub this can easily be made by creating a fork of the main PyWPS repository. Access the PyWPS code repository and click the Fork button. This action creates a copy of the repository associated with your GitHub user. For more details please read the forking guide.
Now you can clone this forked repository into your development environment, issuing a command like:
git clone https://github.com/<github-user>/PyWPS.git pywps
Where you should replace <github-user> with your GitHub user name.
Before you start coding ensure you are working on the master branch:
git checkout master
For the moment, this is the main development branch in the PyWPS project.
You can now start programming your new feature, or fixing that bug you found. Keep in mind that PyWPS depends on a few libraries, refer to the Installation section to make sure you have all of them installed.
3. Commit and pull request¶
If your modification to the code is relatively small and can be included in a single commit then all you need to is reference the issue in the commit message, e.g.:
git commit -m "Fixes #107"
Where 107 is the number of the issue you opened initially in the PyWPS issue tracker. Please refer to the guide on closing issues with commits messages. Then you push the changes to your forked repository, issuing a command like:
git push origin master
Once again, make sure your commit(s) are pushed to the master branch.
Finally you can create a pull request. This is a formal request to merge your contribution with the code base; it is fully managed by GitHub and greatly facilitates the review process. You do so by accessing the repository associated with your user and clicking the New pull request button. Make sure your contribution is not creating conflicts and click Create pull request. If needed, there is also a guide on pull requests.
If you contribution is more substantial, and composed of multiple commits, then you must identify the issue it closes in the pull request itself. Check out this guide for the details.
The members of the PyWPS PSC are then notified of your pull request. They review your contribution and hopefully accept merging it to the code base.
4. Updating local repository¶
Later on, if you wish to make further contributions, you must make sure to be working with the very latest version of the code base. You can add another remote reference in your local repository pointing to the main PyWPS repository:
git remote add upstream https://github.com/geopython/PyWPS
You can use the fetch command to update your local repository metadata:
git fetch upstream
Then you use a pull command to merge the latest commits into your local repository:
git pull upstream master
5. Help and discussion¶
If you have any doubts or questions about this contribution process or about the code please use the PyWPS mailing list or the PyWPS Gitter . This is also the right place to propose and discuss the changes you intend to introduce.
