Contributing to ProgLearn¶
(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 ProgLearn versions. This information can be found by running the following code snippet:
import platform; print(platform.platform()) import sys; print("Python", sys.version) import proglearn; print("ProgLearn", proglearn.__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 ProgLearn is to fork the staging 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
ProgLearnrepo from your GitHub account to your local disk:
$ git clone firstname.lastname@example.org:YourLogin/ProgLearn.git $ cd ProgLearn
featurebranch to hold your development changes:
$ git checkout -b my-feature
Always use a
featurebranch forked from
staging. It’s good practice to never work on the raw
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 (which are a brief summary of The Bits and Brains PR Checklist) 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
staging. In this PR, link relevant issues (either via the use of closing keywords in the comment or by directly linking relevant issues on the lower righthand side of the PR from the web interface), summarize the PR in the title, and comment on the PR with the following format:
#### Reference issue <Example: Closes gh-WXYZ> #### Type of change <Bug, Documentation, Feature Request> #### What does this implement/fix? <Please explain your changes> #### Additional information <Any additional information you think is important>
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.
Properly formatted docstrings are required for documentation generation
ProgLearn package closely follows the numpydoc
guidelines. Please read and follow the
guidelines. Refer to the
provided by numpydoc.
Properly formatted Jupyter notebooks are required for Netlify deployment. It is recommended to check that your tutorial completes the following steps before submitting:
blackformat your notebook. Use the official
Make your tutorial self-contained if possible. It should neither output any file nor read from any file.
Format the first markdown line with "#" at front and make it the one and only informative title instead of using "overview" or other general terms. This line will show up under the tutorials menu.
Format the subtitles with "##" at front so that they will show up as submenus on website.
Minimize cell outputs and avoid unnecessary prints.
Remove all empty cells.
Check the Netlify deployment preview for your PR, which is included as one of the required checks. Be aware that what you see on GitHub or local machine might be different from Netlify deployment, especially math formulas.