Pull Requests via GitHub are the preferred method of contributing code changes to GeoTools.
Pull requests, like patches, are reviewed as a contribution to the codebase. See Contribute for more information.
Talk first policy
Unless you intend to provide a trivial change (fixing typos in the documentation, easy bugfix with test) the very first thing you should do is to subscribe to the GeoTools developer list and explain what you’re about to do.
This is a very important step:
A pull request notifies the GeoTools community of some code changes focused around an issue. It allows the relevant Module Maintainer and others to review the set of changes, discuss issues and suggest fixes before the pull request can be merged into the official repository.
When submitting your pull request:
Jira is used as the project issue tracker. You can include a link to a pull request in JIRA as an alternative to a patch.
A pull request is evaluated using the same standards as a patch, code formatting, test case, and example documentation for any API change.
There maybe reasons why a pull request may not be merged quickly; requiring a unit test is just one example.
To progress the pull request, a conversation with the contributor concerning the issues around the pull request is required. Any discussion regarding the pull request should be confined to its thread established by GitHub. There may be issues raised that are larger than the pull request; take these to mailing lists as appropriate.
If the feedback concerning the pull request have been addressed it can be merged.
If the contributor or other individuals are not willing to address the feedback, then a decision needs to be made regarding the pull request’s future. The module maintainer is in the best position to make this assessment.
While any issues with the pull request may be resolved given the time; it exposes another problem that becomes more likely with time: merge conflicts. The code in the repository changes overtime which may conflict with the new code in the pull request.
While possible; trying to reconcile differences between files is likely to introduce errors. GitHub assists with merging pull request by flagging merge conflicts and disabling the merge option. It is always possible to use Git via the command line to merge the pull request. Avoiding merge conflicts is always preferable.
Avoid Merge Conflicts
The merging of pull requests is ultimately a responsibility of module maintainers, and to a lesser extent members of the PMC. Do not merge pull requests if you are not responsible for the code. For other, act responsibility and collaboratively.
If the pull request’s contributor has followed the guidelines for GeoTools and has written good quality code, then it is likely that the pull request will be merged quickly by the module maintainer.
If there are legitimate reasons for the pull request to remain open they need to be recorded. An example would be a pending feature freeze and a delay will allow GeoTools and upstream projects to deal with ramifications of the change post the freeze.
If no firm decision can be made then leave the pull request open; time may be our friend.
Even if there are no merge conflicts not all pull requests can be accepted by the community.
The simple solution to avoid long standing pull requests, and avoiding merge conflicts; is to simply close the pull request - unmerged. If issues have been discussed and decisions recorded; and there is no impending resolution to the pull request then it is better to close the pull request.
Record the reason why the pull request is being closed unmerged. It is possible to reopen an unmerged pull request at a latter date, resolve merge conflicts and associated issues, and then merge the pull request.
While this is a simple solution there are number of checks before closing an unmerged pull request that will help everyone involved:
There are some questions raised for a long standing pull request.
Long standing pull requests need to be handled appropriately so that everyone benefits. Contributors may learn how to better collaborate with GeoTools. Module maintainers may have to incorporate new features of a problem. Ultimaltely, pull requests are tied to the code base; and, if not handled with care they may lead to problems creating unnecessary work. While the risk of harm is small, the reputation of GeoTools relies upon the integrity of it’s code base and the good work of contributors.
The closing of long standing pull requests provides a barrier; protecting the code base. Also, GitHub lacks the comprehensive search facilities of the like of JIRA. The creation of an associated JIRA issue allows the search facilities of JIRA to be leveraged when looking for information concerning an issue. JIRA has a long history of changes made to the GeoTools project, an invaluable resource. Give it as much information possible for it to be used to the best of its abilities.
In the history of a long standing pull request, there are ample opportunities to talk about issues, document decisions and improve the pull request. These are important facets of working collaboratively in GeoTools. Try to be helpful and keep others informed when handling a long standing pull request.
(Images on this page are Copyrighted © 2013, GitHub, Inc. Used with permission)