.. -*- coding: utf-8 -*-
.. _contributing:

===========================
Contributing to MDAnalysis
===========================

MDAnalysis is a free and open source project. It evolves and grows with the demands of its user base.
The development team very much welcomes contributions from its users.
Contributions can take many forms, such as:

    * **bug reports** or **enhancement requests** filed through the `Issue Tracker`_
    * **bug fixes**
    * **improvements** to the code (speed, clarity, modernised code)
    * **new features** in the code
    * improvements and additions to **documentation** (including typo fixes)
    * improvements to the **build systems**
    * **questions** or **discussions** on `GitHub Discussions`_

The MDAnalysis community subscribes to a `Code of Conduct`_ that all community
members agree and adhere to --- please read it.

.. important::

    The **MDAnalysis** and **MDAnalysisTests** packages are distributed under the `GNU General Public License, version 2 <https://www.gnu.org/licenses/gpl-2.0.html>`_ (or any later version). This is a copyleft license: not only is MDAnalysis open-source, but all derivative work must be as well. **Any code, documentation, or files that you contribute to MDAnalysis will also be made available under this license.** Be sure that you are comfortable with that *before* you push additions to GitHub.

Parts of this page came from the `Contributing to pandas <http://pandas.pydata.org/pandas-docs/stable/contributing.html>`_ guide.

Where to start?
===============

All contributions, bug reports, bug fixes, documentation improvements,
enhancements, and ideas are welcome.

If you are new to Git and version control, have a look at
:ref:`version-control`.

If you are looking to contribute a code or documentation fix, or core feature to MDAnalysis,
and you are brand new to MDAnalysis or open-source development -- we recommend going
through the guides for :ref:`contributing to the main codebase <working-with-mdanalysis-code>`
or the :ref:`user guide <working-with-user-guide>`.

If you are looking to contribute your own project or new addition to MDAnalysis,
we encourage you to open an issue at the `Issue Tracker`_ or consider creating an
`MDAnalysis toolkit (MDAKit)`_ .
MDAKits are standalone packages that build on MDAnalysis to enhance its functionality.
or solve specific scientific or technical problems. MDAKits can be optionally
registered at the `MDAKits registry`_
to advertise to the broader MDAnalysis community.
All packages on the registry are continuously tested
against the latest and development versions of MDAnalysis.

For more on creating an MDAKit, please see the documentation on
`Making an MDAKit`_.



.. _version-control:

Version control, Git, and GitHub
================================

`Git <http://git-scm.com/>`_ is a version control system that allows many people to work together
on a project.
Working with Git can be one of the more daunting aspects of contributing
to MDAnalysis.  Sticking to the guidelines below will help keep the process
straightforward and mostly trouble free.  As always,
if you are having difficulties please feel free to ask for help.

The code is hosted on `GitHub <https://www.github.com/mdanalysis/mdanalysis>`_. To
contribute you will need to sign up for a `free GitHub account
<https://github.com/signup/free>`_.

Some great resources for learning Git:

    * the `GitHub help pages <http://help.github.com/>`_.
    * the `NumPy's documentation <http://docs.scipy.org/doc/numpy/dev/index.html>`_.
    * Matthew Brett's `Pydagogue <http://matthew-brett.github.com/pydagogue/>`_.

------------------------
Getting started with Git
------------------------

`GitHub has instructions <http://help.github.com/set-up-git-redirect>`__ for installing git,
setting up your SSH key, and configuring git.  All these steps need to be completed before
you can work seamlessly between your local repository and GitHub.

.. _`mdnalysis-discussion`:
   http://groups.google.com/group/mdnalysis-discussion
.. _`Code of Conduct`: https://www.mdanalysis.org/pages/conduct/
.. _`Issue Tracker`: https://github.com/MDAnalysis/mdanalysis/issues
.. _`MDAKits registry`: https://mdakits.mdanalysis.org/mdakits.html
.. _`MDAnalysis toolkit (MDAKit)`: https://mdakits.mdanalysis.org/about.html
.. _`Making an MDAKit`: https://mdakits.mdanalysis.org/makingakit.html