Contributing
************

agate actively encourages contributions from people of all genders,
races, ethnicities, ages, creeds, nationalities, persuasions,
alignments, sizes, shapes, and journalistic affiliations. You are
welcome here.

We seek contributions from developers and non-developers of all skill
levels. We will typically accept bug fixes, documentation updates, and
new cookbook recipes with minimal fuss. If you want to work on a
larger feature—great! The maintainers will be happy to provide
feedback and code review on your implementation.

Before making any changes or additions to agate, please be sure to
read about the principles of agate in the About section of the
documentation.


Process for documentation
=========================

Not a developer? That's fine! As long as you can use *git* (there are
many tutorials) then you can contribute to agate. Please follow this
process:

1. Fork the project on GitHub.

2. If you don't have a specific task in mind, check out the issue
   tracker and find a documentation ticket that needs to be done.

3. Comment on the ticket letting everyone know you're going to be
   working on it so that nobody duplicates your effort.

4. Write the documentation. Documentation files live in the *docs*
   directory and are in Restructured Text Format.

5. Add yourself to the AUTHORS file if you aren't already there.

6. Once your contribution is complete, submit a pull request on
   GitHub.

7. Wait for it to either be merged by a maintainer or to receive
   feedback about what needs to be revised.

8. Rejoice!


Process for code
================

Hacker? We'd love to have you hack with us. Please follow this process
to make your contribution:

1. Fork the project on GitHub.

2. If you don't have a specific task in mind, check out the issue
   tracker and find a task that needs to be done and is of a scope you
   can realistically expect to complete in a few days. Don't worry
   about the priority of the issues at first, but try to choose
   something you'll enjoy. You're much more likely to finish something
   to the point it can be merged if it's something you really enjoy
   hacking on.

3. If you already have a task you know you want to work on, open a
   ticket or comment on the existing ticket letting everyone know
   you're going to be working on it. It's also good practice to
   provide some general idea of how you plan on resolving the issue so
   that other developers can make suggestions.

4. Write tests for the feature you're building. Follow the format of
   the existing tests in the test directory to see how this works. You
   can run all the tests with the command "pytest".

5. Write the code. Try to stay consistent with the style and
   organization of the existing codebase. A good patch won't be
   refused for stylistic reasons, but large parts of it may be
   rewritten and nobody wants that.

6. As you are coding, periodically merge in work from the master
   branch and verify you haven't broken anything by running the test
   suite.

7. Write documentation. This means docstrings on all classes and
   methods, including parameter explanations. It also means, when
   relevant, cookbook recipes and updates to the agate user tutorial.

8. Add yourself to the AUTHORS file if you aren't already there.

9. Once your contribution is complete, tested, and has documentation,
   submit a pull request on GitHub.

10. Wait for it to either be merged by a maintainer or to receive
    feedback about what needs to be revisited.

11. Rejoice!


Licensing
=========

To the extent that they care, contributors should keep in mind that
the source of agate and therefore of any contributions are licensed
under the permissive MIT license. By submitting a patch or pull
request you are agreeing to release your code under this license. You
will be acknowledged in the AUTHORS list, the commit history and the
hearts and minds of journalists everywhere.
