.. _gmx-contribute: Contribute to |Gromacs| ======================= |Gromacs| is a community-driven project, and we love getting contributions from people. Contributions are welcome in many forms, including improvements to documentation, patches to fix bugs, advice on the forums, bug reports that let us reproduce the issue, and new functionality. If you are planning to contribute new functionality to |Gromacs|, we strongly encourage you to get in contact with us first at an early stage. New things can lead to exciting science, and we love that. However, the subsequent code maintenance is time-consuming and requires both "up front" and long-term commitment from you, and others who might not share your particular scientific enthusiasm. Please read this page first, and at least post on the `developer discussion forum`_. Looking through the `gmx-developers mailing list archive`_ might also be helpful. Sometimes we'll be able to save you a lot of time even at the planning stage! Much of the documentation is found alongside the source code in the git repository. If you have changes to suggest there, those contributions can be done using the same mechanism as the source code contributions, and will be reviewed in similar ways. Checklist --------- Before you send us your code for review and inclusion into |Gromacs|, please make sure that you have checked all the points on this list: * *Usefulness*: Your code should have wide applicability within the scientific community. You are welcome to have smaller projects tracking our code, but we are not prepared to include and maintain code that will only have limited application. Evidence that people are already using your code or method is one good way to show that your code is useful. Scientific publications is another, but those publications should ideally come from several different research groups to show widespread adoption of the method. * *Advance discussion*: Please communicate with the other developers, e.g. on the `developer discussion forum`_, or `issue tracker`_ to let them know of the general nature of your plans. This will prevent duplicate or wasted effort. It is also a good idea to search those resources as well as the literature and WWW for other projects that may be relevant. * *Verifiable*: If you propose a new method that passes the first check, please make sure that we can easily verify that it will be correct from a physics point of view. That must include documentation (both in the source code and as later additions to the user guide and/or reference manual) that a capable graduate student can read and understand well enough to use your method appropriately. The source code documentation will also help in maintenance and later development. This will be facilitated by the inclusions of unit tests for your code, as described in the section on how to write :ref:`new tests `. We also need some form of automated high-level test of your code, because people who do not understand its details need to be able to change the infrastructure that you depend on. |Gromacs| uses automated continuous-integration testing in :doc:`GitLab `, and we need quick feedback about whether your code would be affected by a proposed change. This means the users of your feature can continue to do good science based upon trustworthy results generated by new versions of |Gromacs| released after you've contributed your feature. * *Structured change process*: Reviewing code for correctness, quality and performance is a very time consuming process, which we are committed to because it is necessary in order to deliver software that is of high enough quality for reliable scientific results. However, human beings are busy and have short attention spans, and a proposed change affecting 10,000 lines of code is likely to generate little enthusiasm from other developers to review it. Your local git commit history is likely full of changes that are no longer present in the version you'd like to contribute, so we can't reasonably review that, either. It might be reasonable to break the process into manageable pieces, such as * the functionality to read the :doc:`mdp settings <../user-guide/mdp-options>` you might require and write a :ref:`tpr`, * the functionality for :ref:`mdrun ` to execute the simplest form of your feature, * further extensions and/or optimizations for your feature, and * functionality for an analysis tool to do useful things with the simulation output. Do get in touch with us, e.g. on the `developer discussion forum`_, to exchange ideas here. * *Timeliness*: We make an annual release of |Gromacs|, with a feature freeze (and git branch fork) on a fixed date, which is agreed more than six months in advance. We still need a month or more to do quality testing on that branch, after the fork and before the release, so there's a period when we cannot accept certain kinds of potentially risky changes. (The main branch will remain open for all kinds of changes, but it is likely that the focus of many of the core developers will be on the release process.) If you have a large change to propose, you need to * make a group of smaller changes, * negotiate in advance who will do the code review, and * have them available for review and improvement months(!) before that date. Even smaller changes are unlikely to be prioritized by others for review in the last month or so! * *Coding style*: Please make sure that your code follows all the :doc:`coding style