Contributing#

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions#

Report Bugs#

Report bugs at ajshajib/dolphin#issues.

If you are reporting a bug, please include:

  • Your operating system name and version.

  • Any details about your local setup that might be helpful in troubleshooting.

  • Detailed steps to reproduce the bug.

Fix Bugs#

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features#

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation#

dolphin could always use more documentation, whether as part of the official dolphin docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback#

The best way to send feedback is to file an issue at ajshajib/dolphin#issues.

If you are proposing a feature:

  • Explain in detail how it would work.

  • Keep the scope as narrow as possible, to make it easier to implement.

  • Remember that this is a volunteer-driven project, and that contributions are welcome. :)

Get Started!#

Ready to contribute? Here’s how to set up dolphin for local development.

  1. Fork the dolphin repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/dolphin.git

  3. Create a branch for local development:

    $ git checkout -b feature/name-of-your-feature

or:

$ git checkout -b bugfix/name-of-your-bugfix

Remember to add ‘bugfix/’ or ‘feature/’ at the beginning of your branch name. Now you can make your changes locally.

  1. When you’re done making changes, check that your changes pass style and unit tests, including testing other Python versions with tox:

    $ tox

To get tox, just pip install it.

  1. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Add detailed description of your changes"
$ git push origin feature/name-of-your-feature

Make sure to start your commit message with a verb, capitalize the first letter, and no period at the end.

  1. Submit a pull request through the GitHub website.

Style Guidelines#

dolphin is written in Python and we want to keep it Pythonic. Generally, we strictly follow PEP 8, and recommend following PEP 257, and 287 as closely as possible. A few key points—that need to be emphasized or are beyond these PEPs—are

  1. Use full words for variable and function/method names with words separated by underscore. Function/method names must start with a verb.

  2. Class names must follow the CamelCase convention.

  3. Class variables and functions/methods that are not intended for use outside of the class/module (i.e., private) must be named with a starting underscore.

  4. No Python lines must be more than 79 characters in length.

  5. Commit messages should be in this format. Note that the first word of the commit title is a verb in present tense, the first letter is capitalized, and there is no period at the end.

    Write commit subject line

    This is an example commit message. Start the commit subject line with a verb. All the verbs are in command form, e.g. fix, add; not in other forms, e.g. fixes, added. The subject line has no period at the end and is followed by a blank line. Add a detailed description about what the commit does in a paragraph after that. No lines in the whole commit message must be more than 72 characters in length.

  6. When in doubt, look in the existing code for examples and follow them.

Pull Request Guidelines#

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.

  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

  3. The pull request should work for Python 3.6, 3.7, and 3.8. Check https://travis-ci.org/ajshajib/dolphin under pull requests for active pull requests or run the tox command and make sure that the tests pass for all supported Python versions.

  4. The pull request should follow the style guidelines given above.

Tips#

To run a subset of tests:

$ py.test test/test_folder_name/test_module_name.py