====================
How to contribute
====================

Contributions are welcome - we want to keep it as easy as possible to contribute
changes that get things working in your environment. There are a few guidelines
that we need contributors to follow so that we can have a chance of keeping on
top of things.

Reporting an Issue
==================

* Make sure you have a `GitHub account <https://github.com/signup/free>`_
* Check if a ticket already exists for your issue on GitHub_.
* If one does not already exist, `create a new ticket`__ 
   + Clearly describe the issue including steps to reproduce when it is a bug.
   + Make sure you include in the earliest version that you know has the issue.

__ GitHub_

Making Changes
==================

* If you haven't already, create a new issue on GitHub_ for your bug
  fix or new feature.
* Fork the repository on GitHub
* Create a topic branch from where you want to base your work.
   + This is usually the master branch.
   + Only target release branches if you are certain your fix must be on that branch.
   + To quickly create a topic branch based on master: 
     ``git checkout -b fix/master/my_contribution master``
   + Please avoid working directly on the ``master`` branch.
* Make commits of logical units.
* Check for unnecessary whitespace with `git diff --check` before committing.
* Make sure your commit messages are in the `proper
  format <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
* Make sure you have added the necessary tests for your changes
* Run the `full test
  suite <http://python.openxcplatform.com/en/master/contributing.html>`_
  to assure nothing else was accidentally broken.

Submitting Changes
==================

* Push your changes to a topic branch in your fork of the repository.
* Sign the `Contributor License Agreement
  <http://openxcplatform.com/contributor-license-agreement.html>`_ (CLA)
* Submit a pull request to the repository in the openxc organization.

Additional Resources
==================

* `General GitHub documentation`_
* GitHub `pull request documentation`_

.. _`General GitHub Documentation`: http://help.github.com/
.. _`pull request documentation`: http://help.github.com/send-pull-requests/
.. _GitHub: https://github.com/openxc/openxc-python/issues
