Submitting patches and features

Where Contributions to Our Code Base Go To

The openPETRA source code is managed with the Git source code versioning system. The official repository of openPETRA can be browsed here: http://code.openpetra.org. This redirects to the OpenPetra Repository at Github.

How We Handle Contributions to Our Code Base

• Write permissions to git origin master are given only to the core members of the development team, just to keep the project on one track.
  • We very much need your contributions though, and we will aim to quickly deal with requests from developers who want to submit patches and code!
• We accept contributions from non-core members of the development team only in a Github Pull Request.
  • You can create your own fork on Github for each feature and for each bug you are working on.

See Submitting patches and features#Workflow for Contributions below for the actual workflow involved.

Initial Setup for Contributing

The contributor (=you) needs to have an account at Github, as we host the openPETRA Git repository on that website.

Please follow the instructions at How to work with git on the command line or How to work with git through the GUI on Windows to get an account at Github.

Workflow for Contributions

1. An Issue needs to be created for every single contribution if there isn't already a bug for it (the bug can also be marked as 'Feature' if it is a feature and not a bug!). The issues are managed in the Github project.
2. You create your own fork of OpenPetra at Github.
   1. Only You will have write access to this fork
   2. Everybody else can see that this fork exists and has read-only access to it
3. You can work on the fork until the the bug is fixed or a new feature is implemented.
   1. Be sure to do frequent 'rebases'/'merges' from the openPETRA trunk to ensure that you have changes that are done in trunk and that your code still compiles against it.
   2. You can commit changes to your branch at any time.
      1. We encourage you to commit your changes to your branch frequently.
      2. Commit your own changes to your branch before doing a rebase/merge. In that way your changes are kept in separate commits from the changes that others did.
      3. Commit the changes that came in through a rebase/merge to your branch immediately after doing a rebase/merge. In that way changes that others did (in trunk) are kept in separate commits from your changes. Use our standard commit message 'merge from trunk'.
4. Once you are done with your bug fix or implementation of a feature:
   1. Ensure everything is committed that you want committed; revert or delete any other files.
   2. Do a last 'rebase'/'merge' from the openPETRA trunk to ensure that you have changes that are done in trunk and that your code still compiles against it.
      1. Resolve any Conflicts. This is best done with the kdiff3 tool (for details see Setup your environment and Resolve conflicts sections.)
      2. Commit just that merge with commit message 'merge from trunk'.
   3. Run nant generateSolution. If you figure that the merge from trunk might have changed significant things in Project files, or has added / deleted C# files then it is prudent to run nant quickClean first to ensure that nant generateSolution is off to a clean start.
   4. Run Unit tests which you might have created in the process and the ones which already exist for the entire openPETRA project after the last 'rebase'/'merge' with command nant test.
   5. Run Uncrustify, our 'code beautifier', using command nant uncrustify. If it made any changes then commit them separately with the simple commit message 'uncrustify'.
   6. Make a request to the core development team members to review your changes and to merge your changes to the openPETRA master.
      1. Create a Github pull request. See https://help.github.com/articles/using-pull-requests/ for details.
5. Once your contribution has been reviewed and it got approved, the changes from your developer branch will be merged into the offical openPETRA trunk by a core developer. You will be informed once this has happened.
6. You are ready for another contribution ;-)