shell
Contributions are what keeps ML Launchpad growing and useful, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Everyone is welcome to contribute, just be nice: Code of Conduct.
You can contribute in many ways:
Report bugs at https://github.com/schuderer/mllaunchpad/issues.
If you are reporting a bug, please search the existing issues to make sure that it is not a duplicate, and 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.
Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
ML Launchpad could always use more documentation, whether as part of the official ML Launchpad docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/schuderer/mllaunchpad/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 :)
Ready to contribute? Here's how to set up mllaunchpad
for local development.
- Fork the
mllaunchpad
repo on GitHub. Clone your fork locally:
$ git clone [email protected]:your_name_here/mllaunchpad.git
Install your local copy for development. We recommend to use a virtual environment and are going to use
venv
in our examples (though any kind of virtual environment should work):$ cd mllaunchpad/ $ python -m venv .venv
Activate the virtual environment:
$ source .venv/bin/activate
(On Windows, use the command
.venv\Scripts\activate.bat
.)Install the mllaunchpad package in editable mode. This includes its development requirements:
$ pip install -e .[dev]
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally. Don't forget to create tests for your code. We use Google style, particularly docstrings.
Add the upstream remote. This saves a reference to the main mllaunchpad repository, which you can use to keep your repository synchronized with the latest changes:
$ git remote add upstream https://github.com/schuderer/mllaunchpad.git
It is often helpful to keep your local branch synchronized with the latest changes of the main mllaunchpad repository:
$ git fetch upstream $ git merge upstream/master
To quickly test just the relevant modified files while still developing:
$ pytest tests.test_module_testing_your_changes
When you're done making changes, run
nox
to check that your changes pass all style checks and tests. This also reformats your code:$ nox
For more fine-grained control, you can
nox -s a_session_name
to only perform specific tests or checks. Runnox -l
for a list of available sessions.Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes" $ git push origin name-of-your-bugfix-or-feature
Some tips for good commit messages.
- Submit a pull request through the GitHub website:
base: master <- compare: name-of-your-bugfix-or-feature
. Reference relevant GitHub issues by including their #<issue_number> in the pull request description.
Before you submit a pull request, check that it meets these guidelines:
- Make sure you have checked that it is not a duplicate, and it should be an attempt to solve a issue on GitHub. If no such issue exists, it is never a bad idea to create one first. This offers the chance to discuss the proposed change you propose with maintainers and other users before doing the actual work.
- The pull request should include tests.
- If the pull request adds or changes functionality, the docs should be updated. Update and add docstrings as needed, and update the
docs/usage.rst
, and if it's a major addition, theREADME.rst
. List your contribution in theUnreleased
section ofCHANGELOG.rst
. - The pull request should work for Python 3.6 and 3.7. Check https://travis-ci.org/schuderer/mllaunchpad/pull_requests and make sure that the tests pass for all supported Python versions.
If installing the development requirements (pip install -e .[dev]
) fails, try to run the command again.
To run a subset of tests:
$ pytest tests.test_module_testing_your_changes
If on step 3, you get an error creating the virtual environment and are on an Anaconda, installation, you might need to update conda and then python before being able to create the virtual environment:
$ conda update -n base -c defaults conda
$ conda update python
On step 5: When editing documentation, it is handy to see your edits reflected in the docs on-the-fly:
$ nox -s docs -- monitor
On step 4 or 6, you might get a merge conflict on docs/_static/examples.zip
. This file is generated automatically by nox when building the docs, and differences lead to a different file. To resolve:
$ git checkout --ours -- docs/_static/examples.zip
$ git add docs/_static/examples.zip
$ git commit
Then continue with what you wanted to do (in case of step 4, working on your code, in case of step 6, pushing).
A reminder for the maintainers on how to deploy. Make sure all your changes are committed and do the following:
- Decide on the new version number (e.g.
2.1.23
, use semantic versioning). - Create a new branch to contain the release-related changes.
- Make sure
CHANGELOG.rst
is complete and move all unreleased changes under a new header for this version. - Change the line
version = ...
insetup.cfg
to the new version number. - Run
nox
again to make sure you did not break anything. - Commit and push the changes and create a pull request.
- Modify/correct things in the PR to your heart's content, and when satisfied, merge it to
master
. - On GitHub, create a draft release with a tag name like e.g.
v2.1.23
, at targetmaster
, and a name like e.g.Release 2.1.23
. - Get the doc's changes and paste them into the description (make them look nice).
- Publish the release.
- Check that Travis CI deployed the release to PyPI successfully.
Alternatively, you can also release mllaunchpad
with these commands (assuming you have already committed your version and changelog changes):
$ git tag -a v2.1.23 -m "Bump version to v2.1.23"
$ git push
$ git push --tags
In either case, Travis-CI will then deploy to PyPI if tests pass.