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 features, 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 nosetests tests.
  5. Verify your tests work on all supported versions of Python by runing tox.
  6. 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.
  7. As you are coding, periodically merge in work from the master branch and verify you haven’t broken anything by running the test suite.
  8. 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.
  9. Add yourself to the AUTHORS file if you aren’t already there.
  10. Once your contribution is complete, tested, and has documentation, submit a pull request on Github.
  11. Wait for it to either be merged by a maintainer or to receive feedback about what needs to be revisited.
  12. 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.