|Table of Contents|
MidPoint is open to contributions. Any contribution is appreciated whether it is documentation update, localization, bugfix or a new feature. Anyone can start experimenting with midPoint code without the need to ask for any privileges or access to our source code repository. Git distributed development model allows this to be done easily. This pages describes how to do it. It describes how to create and contribute a simple bugfix and also how to cooperate with the midPoint team in a longer run.
Git is a distributed version control system that we use to maintain midPoint source code. Its non-centralized character allows for a variety of development models and workflows. This page describes just two possible scenarios but almost any approach supported by git is possible to use with midPoint development. Although it is easy to start contributing to midPoint by following the instructions on this page understanding of Git principles is important for efficient midPoint development. Please see our Git page for more details about git, location of our source code repositories, tips for using git software, etc.
This is the primary midPoint repository. GitHub users may use this repository to submit a contribution. This is the easiest way how individual developers can contribute to midPoint. Please see see Development Participation page and github documentation for the details.
Traditional Git Usage
The easiest way for individual developers to contribute patches is by using github. The process goes like this:
- Fork the repository. Github provides a very convenient "fork" button that creates your own copy of midPoint repository. You will have read-write permission to this copy.
- Develop your contribution on the "fork". Use it just like any other git repository.
- Pull request. Github provides another convenient button to issues a pull request when your contribution is done. The pull request is a request to merge your contribution to the main midPoint development branch. When you issues a pull request the midPoint maintainer will be notified. Shortly after this you will be contacted by the maintainer if any additional steps are needed.
Individual Developers: Mailing list
There is another and more traditional way how to contribute patches to midpoint by using the mailing list. This does not require a github account, any server software or any other difficult setup. Following examples assume the use of git command-line tools. However similar approach should also be possible by using Git GUIs. This method is ideal for contributing small pieces of work (one or two commits at a time) done by individual developers. It is less suitable for contributing larger pieces of work and it is not suitable for larger development teams.
One of midPoint maintainers will notice the patch in the mailing list. He will use the
git am command to extract and apply the patches to the main midPoint repository. The maintainer also checks that the patches apply cleanly and that everything works well. The maintainer may contact the patch author in case of any issues. If everything goes will the maintainer then pushes the commits to the main midPoint repository.
Larger development teams will need their own repository to work on. The work in the team needs to be shared before it is complete and ready to be contributed. Therefore a server-side clone of the main midPoint repository is needed. This can be done by self-hosting the repository by installing git server-side tools or by using the services of a hosting site such as GitHub.
One of midPoint maintainers gets the pull request from the mailing list. He adds the partner repository as one of his git remotes and pulls the commits from it. He does all merging with the current development branches as necessary. The maintainer makes sure that the commits merge smoothly with the current code and that everything works well. The maintainer may contact the patch author in case of any issues. If everything goes will the maintainer then pushes the commits to the main midPoint repository.
Tips and Best Practice
- Do not submit each individual commit unless the commit itself is a complete contribution. If your contribution is divided into several commits (which is perfectly fine) then send all the commits together so the maintainer can apply and test them together.
- If you have many commits but you want only to show them as one in the final midPoint history you might want to squash these commits to one. You can use git interactive rebasing to do this. (
git rebase -i, the Git book provides more details)
- Provide a meaningful commit message. If the commit message is longer than a single line provide a short summary of the message in the first line and then provide more details in subsequent lines. Most git tools display just the first line of the commit message therefore the developers should be able to get an idea about the commit just from the first line.
- You may want to create a topic branch for larger contributions.
- There is no code ownership principle. Not in the midPoint development team and we do not provide that to the contributions as well. All code "belongs" to every developer and anyone has the "right" to modify any code. The only thing that we care about is the quality of the modification, not its origin. Therefore feel free to modify any code and fix bugs anywhere in the midPoint core or in any of the contributions. Just please make sure you know what you are doing. If you are not you are free to discuss that on
midpoint-devmailing list. If you contribute a code be prepared that others may modify it. If you do not want others to "ruin" you code then do not contribute it.
- MidPoint core team is trying to be quite careful about the state of the
masterbranch in main midPoint repository. We try very hard not to break the build and we are also careful about passing tests and overall code quality. But this is software development and we are only human beings. Therefore it may happen that we break something occasionally. Therefore it is good idea to check the state of the source code before pulling from the main midPoint repository. The easiest way to do this is by looking at our continuous integration system (Bamboo). If it is mostly green then it is probably OK to pull changes. If it is too red it is better to postpone the pull for a while.
- Also write tests not just the main code. If you are fixing a bug try to write a test for the bug first and fix the bug second. For larger pieces of functionality try to create a fair amount of test code. Submit the tests as part of your contribution. You write the tests for your own good. As there is no code ownership anyone might (unintentionally) break your code. If you have good tests for the code the problem will be detected soon after the modification while it is still easy to fix. If you have no tests then you code will break without anyone noticing it for quite a long time. This will cause that your contribution might "corrode" over time and it may even be removed from the main code if its quality drops too low.
- For more details about contributing using git please see the "Distributed Git - Contributing to a Project" chapter of the Git book. In fact the whole book is more than worth reading.
Licence and Credit
MidPoint is developed under Apache Licence. By submitting your contribution to the main midPoint repository you agree to the terms of the Licence and you contribute your work under this licence. There is no other contributor agreement and we do not ask for copyright assignment. All work is licensed under the Apache licence. That's the only rule. We are very strict about maintaining midPoint open source character and therefore we will not accept any contribution under a different licence (using publicly available third-party open source libraries is OK as long as they are available under any compatible OSI-approved licence). Each new contributed file must have appropriate header declaring licensing under Apache Licence otherwise the contribution will be refused.
Git maintains the commit meta-data of the original commit. And this is what will be recorded in the history trail of main midPoint repository. Therefore the original contributor will be recorded in each commit. Apart from this the contributors are free to add their names to the appropriate place in the file header (e.g. Java
@author annotation) if they feel their contribution is big enough to justify it.
See Development Participation page.
Licence and Credit
See Development Participation page.