.. _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
the following pages first, and at least post on the `developer discussion forum`_.
Looking through the `gmx-developers mailing list archive`_ might also be
helpful. Sometimes we will 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 <gmx-make-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 <gitlab-ci>`,
  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 have
  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 would like to contribute, so we
  cannot 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 <gmx 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 is 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 <style>` and :ref:`code formatting <code-formatting>`
  guidelines. This will make the code review go more smoothly on both sides. There are a number of
  tools already included with |Gromacs| to facilitate this, please have
  a look at :ref:`the respective part of the documentation <gmx-codeformatting>`.

* *Code documentation*: To ensure proper code documentation, please follow the
  instructions provided for the use of :doc:`doxygen <doxygen>`. In addition to this,
  the new functionality should be documented in the manual and possibly the user guide .

* In addition to coding style, please also follow the instructions given
  concerning the :ref:`commit style <code-commitstyle>`. This will also
  facilitate the code review process.

Preparing code for submission
-----------------------------

|Gromacs| uses ``git`` for :doc:`change-management`.
Instead of accepting "pull requests", |Gromacs| changes are submitted as individual
commits on the tip of the ``main`` branch hosted at `gitlab`_.
Preparing, submitting, and managing patches for a change requires a little bit
of set-up. Refer to :doc:`change-management` for information about

* accessing the |Gromacs| *git* repository
* structure of the repository
* source control without merge commits
* ``git`` usage that may be less common in other development work flows

Alternatives
------------

|Gromacs| has a public mirror available on GitHub at
https://github.com/gromacs/gromacs. You may wish to fork the project
under your own GitHub account and make your feature available that
way. This should help you to generate a following of users that would
help make the case for contributing the feature to the core. This
process would then still need to follow the remaining criteria
outlined here.  If you fork |Gromacs|, please set the CMake variable
``GMX_VERSION_STRING_OF_FORK`` to an appropriate descriptive string
- see cmake/gmxVersionInfo.cmake for details.

There is a project underway to develop a stable API for |Gromacs|,
which promises to be a great tool for permitting innovation while
ensuring ongoing quality of the core functionality. You might prefer
to plan to port your functionality to that API when it becomes
available. Do keep in touch on the `developer discussion forum`_, so
you will be the first to know when such functionality is ready for people to
explore!

Do you have more questions?
---------------------------

If you have questions regarding these points, or would like feedback on your ideas for contributing,
please feel free to contact us through the `developer discussion forum`_.
If your code is of interest to the wider |Gromacs| community, we will be happy to assist you
in the process of including it in the main source tree.

Removing functionality
----------------------

This is occasionally necessary, and there is :ref:`policy for such
occasions <deprecation-policy>`.
For users, there are also lists of anticipated changes,
including deprecated functionality,
in the "Major release" :ref:`notes <release-notes>`.
