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