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.
Communication with core midPoint development team is crucial for any successful participation in midPoint development. There are several methods to communicate with the core team:
- Mailing lists are general-purpose communication mechanisms for midPoint community. All mailing lists are public. Almost any conversation is allowed on mailing lists as long as it is kept reasonable and polite. This includes conversation regarding development topics. However, the nature of a mailing list can make the conversation somehow slow and inflexible.
- Bug-tracking System is open to anyone to search, open a bug report or participate on existing bug reports.
- Development chat room on gitter can be used as a faster communication channel. The room is public. However, the room is limited to development conversations. It is OK to discuss your contribution, planned contribution, development idea, localization, documentation updates and similar topics on this chat. However, the chat room is not supposed to be a replacement for subscription and support.
- There are other private communication channels available for midPoint subscribers - and platform subscribers in particular. Please contact Evolveum for the details.
Public community communication
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.
Evolveum maintains midPoint repository on GitHub:
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. Simply fork midPoint project on github, make the changes and when finished create a pull request.
Please see github documentation for the details.
Traditional Git Development
There is also a traditional way how to collaborate using git. This method is rarely used. But we still support it if you happen to prefer this method. See Traditional Use of Git page for details.
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.
- If there is an "issue" created in our bug-tracking system it is recommended to include issue identifier in the commit message.
- 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. 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 (e.g. integration 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 - except for hard copyleft licenses such as GPL). Each new contributed file must have appropriate header declaring licensing under Apache Licence otherwise the contribution might 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.