Dev guide: How to make your first (code) contribution

Contributions to JGraphT can be made in many forms: through code, by answering questions on the mailing list, by updating our website, or simply by fixing javadoc typos. Any form of contribution is welcome! This guide is intended as a roadmap to a successful code contribution.

1. Setup your development environment
2. Before you start implementing, please discuss your idea with us first. Sometimes, functionality already exists, is already being implemented by someone else, or is simply not a good fit for jgrapht. For ideas on what to implement, see the "Open tasks, projects and collaboration ideas" page (we try to keep this page up-to-date, but it is better to check whether some task has already been performed). Notice that algorithmic implementations must be based on academic publications (books, papers, phd dissertations).
3. Take note of the contributor guidelines

a. Writing a new class or package.

In order to write a new class or package, follow these steps:

1. Each new class you add needs a copyright header. This header can be found in any of the existing classes. Simply copy and paste the header. The only modifications you are allowed to make to the header are the year, and your name on the first line. The first line of the header should read:
   * (C) Copyright <current year>-<current year>, by <your name> and Contributors.
   Here's an example:
   * (C) Copyright 2017-2017, by Barak Naveh and Contributors.
   It is very important that you strictly adhere to this format. Copyright headers are updated by automated scripts; deviation from the default format interferes with the automated update process.
2. Implement your classes. Have a look at the structure and style of existing classes with similar functionality. Do not modify HISTORY.md or CONTRIBUTORS.md yourself; we do that for you. This prevents a lot of merge conflicts.
3. Every new class you write needs to be accompanied by tests
4. Write proper documentation.
5. OPTIONAL: Whenever you implement a new algorithm, make sure to place it in the right package. Moreover, your algorithm should implement the correct interface from org.jgrapht.alg.interfaces. If no suitable package exists, create a new one, and add a new package-info.java file containing the package description. If applicable, consider adding a new interface to org.jgrapht.alg.interfaces.

b. Augmenting existing code.

Whenever you are making modifications to existing code, e.g. fixing a bug, or adding additional functionality, follow these steps:

1. Make your modifications to the existing code. Keep style and structure consistent. Do not modify HISTORY.md or CONTRIBUTORS.md yourself; we do that for you. This prevents a lot of merge conflicts.
2. In case you added new functionality, write proper documentation and corresponding unit tests.
3. Run the existing unit tests to ensure that you didn't break anything.
4. In case you made considerable modifications to a file (not just a typo), consider adding yourself to the @author list. Do not modify the Copyright header by adding your name to it! You are covered by the "and Contributors" clause in the copyright header.
5. If your change required edits in any example code, please make sure that the corresponding tutorial pages remain consistent.

Finishing your contribution

1. Add, commit and push your changes to your repository.
2. Verify whether your code passes all our tests, and meets our style and coding conventions. To do this, run:

   mvn clean
   mvn verify
   mvn checkstyle:check -P checkstyle
   mvn javadoc:aggregate
   

   In case of errors/warnings, go back and fix them.
3. Once you are satisfied (i.e completed your code, documentation, and tests following the instructions above), create a Pull Request. Provide a proper description for the reviewers: what is it that you are submitting? Are you fixing a bug? If so, describe the bug, and how you fixed it.
4. Wait for a code review. This may take some time. In case changes are required, add, commit and push your changes to your branch. The Pull Request gets automatically updated.