Skip to content

Latest commit

 

History

History
134 lines (85 loc) · 5.52 KB

CONTRIBUTING.md

File metadata and controls

134 lines (85 loc) · 5.52 KB
Raw

Contributing to Poutyne

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features
  • Becoming a maintainer

We Develop with Github

We use github to host code, to track issues and feature requests, as well as accept pull requests.

We Use Github Flow, So All Code Changes Happen Through Pull Requests

Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:

  1. Fork the repo and create your branch from the dev branch.
  2. If you've added code that should be tested, you must ensure it is properly tested.
  3. If you've changed APIs, update the documentation.
  4. Ensure the Travis test suite passes.
  5. Make sure your code lints.
  6. Submit that pull request!

Any contributions you make will be under the LGPLv3 Software License

In short, when you submit code changes, your submissions are understood to be under the same LGPLv3 License that covers the project. Feel free to contact the maintainers if that's a concern.

Write bug reports with detail, background, and sample code

We use GitHub issues to track public bugs. Report a bug by opening a new issue. You should use one of our proposed templates when appropriate; they are integrated with GitHub and do most of the formatting for you. It's that easy!

Great Bug Reports tend to have:

  • A quick and clear summary and/or background
  • Steps to reproduce
    • Be specific and clear!
    • Give sample code if you can. Try to reduce the bug to the minimum amount of code needed to reproduce: it will help in our troubleshooting procedure.
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) Feel free to include any print screen or other file you feel may further clarify your point.

Do you have a suggestion for an enhancement?

We use GitHub issues to track enhancement requests. Before you create an enhancement request:

  • Make sure you have a clear idea of the enhancement you would like. If you have a vague idea, consider discussing it first on the users list.

  • Check the documentation to make sure your feature does not already exist.

  • Do a quick search to see whether your enhancement has already been suggested.

When creating your enhancement request, please:

  • Provide a clear title and description.

  • Explain why the enhancement would be useful. It may be helpful to highlight the feature in other libraries.

  • Include code examples to demonstrate how the enhancement would be used.

Prerequisites

We created three requirements files to install all the tools used for the development of the library. tests/requirements.txt define the requirements for the tests, styling_requirements.txt for the styling and docs/requirements.txt for the documentation.

You can install all the requirements with

pip install -r tests/requirements.txt
pip install -r styling_requirements.txt
pip install -r docs/requirements.txt

Also, you should run python setup.py develop to build the project and be able to build the documentation.

python setup.py develop

Use a Consistent Coding Style

All of the code is formatted using black with the associated config file. In order to format the code of your submission, simply run

See the styling requirements for the proper black version to use.

black .

We also have our own pylint config file. Try not to introduce code incoherences detected by the linting. You can run the linting procedure with

See the styling requirements for the proper pylint version to use.

pylint poutyne
pylint tests

Tests

If your pull request introduces a new feature, please deliver it with tests that ensure correct behavior. All of the current tests are located under the tests folder, if you want to see some examples.

For any pull request submitted, ALL of the tests must succeed. You can run the tests with

pytest tests

Documentation

When submitting a pull request for a new feature, try to include documentation for the new objects/modules introduced and their public methods.

All of Poutyne's html documentation is automatically generated from the Python files' documentation. To have a preview of what the final html will look like with your modifications, first start by rebuilding the html pages.

cd docs
./rebuild_html_doc.sh

You can then see the local html files in your favorite browser. Here is an example using Firefox:

firefox _build/html/index.html

License

By contributing, you agree that your contributions will be licensed under its LGPLv3 License.

References

This document was adapted from the open-source contribution guidelines for Facebook's Draft.