--- /dev/null
+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 mailing
+list`_. 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 mailing list`_ mailing list, or `Redmine
+ <https://redmine.gromacs.org>`_ 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 implemented by our
+ :doc:`jenkins <jenkins>` server, 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 <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 mailing list`_, 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 master 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-uncrustify>`.
+
+* *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.
+
+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.
+
+There is a project underway to develop a stable API for |Gromacs|,
+which promises to be a great tool for permtting 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 mailing list`_, so
+you'll 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 mailing list`_.
+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.
+
+.. _developer mailing list: https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx-developers
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff