1 Contribute to |Gromacs|
2 =======================
4 |Gromacs| is a community-driven project, and we love getting
5 contributions from people. Contributions are welcome in many forms,
6 including improvements to documentation, patches to fix bugs, advice
7 on the forums, bug reports that let us reproduce the issue, and new
10 If you are planning to contribute new functionality to |Gromacs|, we
11 strongly encourage you to get in contact with us first at an early
12 stage. New things can lead to exciting science, and we love
13 that. However, the subsequent code maintenance is time-consuming and
14 requires both "up front" and long-term commitment from you, and others
15 who might not share your particular scientific enthusiasm. Please read
16 this page first, and at least post on the `developer mailing
17 list`_. Sometimes we'll be able to save you a lot of time even at the
20 Much of the documentation is found alongside the source code in the
21 git repository. If you have changes to suggest there, those
22 contributions can be done using the same mechanism as the source code
23 contributions, and will be reviewed in similar ways.
28 Before you send us your code for review and inclusion into |Gromacs|,
29 please make sure that you have checked all the points on this list:
31 * *Usefulness*: Your code should have wide applicability within the scientific
32 community. You are welcome to have smaller projects tracking our code,
33 but we are not prepared to include and maintain code that will only have
34 limited application. Evidence that people are already using your code or
35 method is one good way to show that your code is useful.
36 Scientific publications is another, but those publications should
37 ideally come from several different research groups to show
38 widespread adoption of the method.
40 * *Advance discussion*: Please communicate with the other developers,
41 e.g. on the `developer mailing list`_ mailing list, or `Redmine
42 <https://redmine.gromacs.org>`_ to let them know of the general
43 nature of your plans. This will prevent duplicate or wasted
44 effort. It is also a good idea to search those resources as well as
45 the literature and WWW for other projects that may be relevant.
47 * *Verifiable*: If you propose a new method that passes the first check,
48 please make sure that we can easily verify that it will be correct
49 from a physics point of view. That must include documentation (both
50 in the source code and as later additions to the user guide and/or
51 reference manual) that a capable graduate student can read and
52 understand well enough to use your method appropriately. The source
53 code documentation will also help in maintenance and later
56 This will be facilitated by the inclusions of unit tests for your code,
57 as described in the section on how to write
58 :ref:`new tests <gmx-make-new-tests>`.
60 We also need some form of automated high-level test of your code,
61 because people who do not understand its details need to be able to
62 change the infrastructure that you depend on. |Gromacs| uses
63 automated continuous-integration testing implemented by our
64 :doc:`jenkins <jenkins>` server, and we need quick feedback about whether your
65 code would be affected by a proposed change. This means the users of
66 your feature can continue to do good science based upon trustworthy
67 results generated by new versions of |Gromacs| released after you've
68 contributed your feature.
70 * *Structured change process*: Reviewing code for correctness, quality
71 and performance is a very time consuming process, which we are
72 committed to because it is necessary in order to deliver software
73 that is of high enough quality for reliable scientific
74 results. However, human beings are busy and have short attention
75 spans, and a proposed change affecting 10,000 lines of code is
76 likely to generate little enthusiasm from other developers to review
77 it. Your local git commit history is likely full of changes that are
78 no longer present in the version you'd like to contribute, so we
79 can't reasonably review that, either. It might be reasonable to
80 break the process into manageable pieces, such as
82 * the functionality to read the :doc:`mdp settings <../user-guide/mdp-options>` you might require and
84 * the functionality for :ref:`mdrun <gmx mdrun>` to execute the simplest form of your
86 * further extensions and/or optimizations for your feature, and
87 * functionality for an analysis tool to do useful things with the
90 Do get in touch with us, e.g. on the `developer mailing list`_, to
93 * *Timeliness*: We make an annual release of |Gromacs|, with a feature
94 freeze (and git branch fork) on a fixed date, which is agreed more
95 than six months in advance. We still need a month or more to do
96 quality testing on that branch, after the fork and before the
97 release, so there's a period when we cannot accept certain kinds of
98 potentially risky changes. (The master branch will remain open for
99 all kinds of changes, but it is likely that the focus of many of the
100 core developers will be on the release process.) If you have a large
101 change to propose, you need to
103 * make a group of smaller changes,
104 * negotiate in advance who will do the code review, and
105 * have them available for review and improvement months(!) before
106 that date. Even smaller changes are unlikely to be prioritized
107 by others for review in the last month or so!
109 * *Coding style*: Please make sure that your code follows all the
110 :doc:`coding style <style>` and :ref:`code formatting <code-formatting>`
111 guidelines. This will make the code review go more smoothly on both sides. There are a number of
112 tools already included with |Gromacs| to facilitate this, please have
113 a look at :ref:`the respective part of the documentation <gmx-uncrustify>`.
115 * *Code documentation*: To ensure proper code documentation, please follow the
116 instructions provided for the use of :doc:`doxygen <doxygen>`. In addition to this,
117 the new functionality should be documented in the manual and possibly the user guide .
119 * In addition to coding style, please also follow the instructions given
120 concerning the :ref:`commit style <code-commitstyle>`. This will also
121 facilitate the code review process.
126 |Gromacs| has a public mirror available on GitHub at
127 https://github.com/gromacs/gromacs. You may wish to fork the project
128 under your own GitHub account and make your feature available that
129 way. This should help you to generate a following of users that would
130 help make the case for contributing the feature to the core. This process
131 would then still need to follow the remaining criteria outlined here.
133 There is a project underway to develop a stable API for |Gromacs|,
134 which promises to be a great tool for permtting innovation while
135 ensuring ongoing quality of the core functionality. You might prefer
136 to plan to port your functionality to that API when it becomes
137 available. Do keep in touch on the `developer mailing list`_, so
138 you'll be the first to know when such functionality is ready for people to
141 Do you have more questions?
142 ---------------------------
144 If you have questions regarding these points, or would like feedback on your ideas for contributing,
145 please feel free to contact us through the `developer mailing list`_.
146 If your code is of interest to the wider |Gromacs| community, we will be happy to assist you
147 in the process of including it in the main source tree.
149 .. _developer mailing list: https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx-developers