Contributing to mgc¶
(adopted from scikit-learn)
Submitting a bug report or a feature request¶
We use GitHub issues to track all bugs and feature requests; feel free to open an issue if you have found a bug or wish to see a feature implemented.
In case you experience issues using this package, do not hesitate to submit a ticket to the Issue Tracker. You are also welcome to post feature requests or pull requests.
It is recommended to check that your issue complies with the following rules before submitting:
How to make a good bug report¶
When you submit an issue to Github, please do your best to follow these guidelines! This will make it a lot easier to provide you with good feedback:
The ideal bug report contains a short reproducible code snippet, this way anyone can try to reproduce the bug easily (see this for more details). If your snippet is longer than around 50 lines, please link to a gist or a github repo.
If not feasible to include a reproducible snippet, please be specific about what classes and/or functions are involved and the shape of the data.
If an exception is raised, please provide the full traceback.
Please include your operating system type and version number, as well as your Python and mgc versions. This information can be found by running the following code snippet:
import platform; print(platform.platform()) import sys; print("Python", sys.version) import mgc; print("mgc", mgc.__version__)
Please ensure all code snippets and error messages are formatted in appropriate code blocks. See Creating and highlighting code blocks for more details.
The preferred workflow for contributing to mgc is to fork the main repository on GitHub, clone, and develop on a branch. Steps:
Fork the project repository by clicking on the ‘Fork’ button near the top right of the page. This creates a copy of the code under your GitHub user account. For more details on how to fork a repository see this guide.
Clone your fork of the
mgcrepo from your GitHub account to your local disk:
$ git clone firstname.lastname@example.org:YourLogin/mgc.git $ cd mgc
featurebranch to hold your development changes:
$ git checkout -b my-feature
Always use a
featurebranch. It’s good practice to never work on the
Develop the feature on your feature branch. Add changed files using
git addand then
$ git add modified_files $ git commit
to record your changes in Git, then push the changes to your GitHub account with:
$ git push -u origin my-feature
Pull Request Checklist¶
We recommended that your contribution complies with the following rules before you submit a pull request:
Follow the coding-guidelines.
Give your pull request a helpful title that summarises what your contribution does. In some cases
Fix <ISSUE TITLE>is enough.
Fix #<ISSUE NUMBER>is not enough.
All public methods should have informative docstrings with sample usage presented as doctests when appropriate.
At least one paragraph of narrative documentation with links to references in the literature (with PDF links when possible) and the example.
All functions and classes must have unit tests. These should include, at the very least, type checking and ensuring correct computation/outputs.
Ensure all tests are passing locally using
pytest. Install the necessary packages by:
$ pip install pytest pytest-cov
or you can run pytest on a single test file by
$ pytest path/to/test.py
Run an autoformatter. We use
blackand would like for you to format all files using
black. You can run the following lines to format your files.
$ pip install black $ black path/to/module.py
Uniformly formatted code makes it easier to share code ownership.
package closely follows the official Python guidelines detailed in
PEP8 that detail how
code should be formatted and indented. Please read it and follow it.