Dev guide: Become a Contributor
- Adopt a highway
- Dev guide
- Become a Contributor
- Coding and Style Conventions
- Contributor Guidelines
- Deprecation policy
- How to add example code
- How to make your first (code) contribution
- How to setup your development environment for JGraphT
- How to write documentation
- Maven Plugin Installation Guide
- Open tasks, projects and collaboration ideas
- Unit testing
- Website Deployment
- Writing new wiki pages
Clone this wiki locally
Want to become a contributor to JGraphT? You've come to the right place. But before you start putting together a pull request, there are some items you should think through that may save you and us a lot of time.
Most importantly: unless your contribution is a very small pull request (i.e. under 20 lines of functional code), you should not send it to us without discussing it first. Usually the best place to do this is in a new github issue. This discussion provides a good example of how to go about this. If you skip this step, there's a good chance that your pull request will be ignored by all committers (or just closed with a comment linking to this page).
Here are some points to think through and summarize when making your proposal:
- What academic/research publications is your work based on? Besides helping us understand the relevance of your contribution, it will also help us in checking its correctness. Algorithmic contributions which are not based on scientific literature are often rejected.
- Have you familiarized yourself with the JGraphT codebase? If your suggestion overlaps with existing functionality, or issues that have already been raised, you should be aware of that and explain how you're addressing the overlap. Are you comfortable following the existing patterns and conventions set by the library? You might want to warm up with a small bugfix or enhancement first before starting on a large contribution.
- What approach are you taking to the problem, and how will you guarantee an efficient solution? What existing data structures or utilities can you reuse, and which new ones will you need to implement yourself?
- Where will your code live? Is it a data structure, algorithm, view, utility, demo, generator, importer/export, none of the above, all of the above, what? If it's an algorithm, does it belong in one of the existing alg subpackages, or is it a new area? Moving code around during code review makes the process take much longer, so it's much more efficient to figure out the answers to these questions ahead of time.
- If your contribution is large, would it be possible to break it down into a series of self-contained pull requests? It's much easier and faster for us to review a small pull request, and the experience you gain from the first one is likely to smooth out the reviews for the subsequent requests. Here "self-contained" means the pull request would be releasable on its own, even if we decided not to include any followups.
- Your PR should be substantial. Changing/adding/removing a single word/phrase, a typo etc is not considered a substantial contribution.
- Do you have the necessary IP rights to be contributing code to open source projects? If you're doing it as part of employment by a company, there's a good chance you need their permission first.
If you don't have answers to all of these questions, that's OK...you can raise them in the github issue and we'll try to answer them there. This is much more efficient than submitting a big pile of code first and then having us suggest drastic changes.
Once you've gotten the green light on the github issue, you can start getting your code in shape for submitting a pull request. We have a separate page with details on how to go about that.
Project committers operate on a volunteer basis, and may have limited time to spend on code review. As a result, the process may take much longer than you expect. Please be patient!
To get an idea of what a long process it can be (especially when a lot of issues are hashed out on the fly rather than up front), take a look at this pull request, which was eventually merged.
And this pull request provides a good example of behavior to avoid during code review.
If all goes well, your contribution will eventually be merged into the JGraphT codebase. However, in some cases, this just won't happen. Here are some typical reasons why:
- consensus from committers was that the contribution was not a good fit for the library (likewise for any dependencies you use)
- contribution was incomplete (i.e. if we included it in the codebase as is, we would not feel comfortable making a release containing it)
- you failed to find an acceptable resolution for all issues raised during code review
- your contribution was too large or too complicated for us to be able to dedicate the necessary time for code review
- contribution code quality was not up to our standards, and the review effort required to address this would be excessive
- IP issues (e.g. license incompatibility in a dependency)
When this happens, it's disappointing, but it's not the end of the world. Open source provides you with some good fallback options:
- If possible, create your own small open source library which depends on JGraphT, and publish your code there. This may not work for changes to the core structures of JGraphT, but we provide numerous extension points which allow you to customize their behavior in your extension, so maybe you can use one of those. If you go this route, feel free to add a link to your project from our wiki page so that other users can find it.
- Last resort: maintain your own fork of JGraphT. This can require a lot of maintenance effort over time, but it gives you complete freedom as long as you respect the JGraphT licensing.