docs/dev-manual/contribute.rst

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