Contributing guidelines

See the Docker contributing guidelines. The following is specific to Docker SDK for Python.

Thank you for your interest in the project. We look forward to your contribution. In order to make the process as fast and streamlined as possible, here is a set of guidelines we recommend you follow.

Reporting issues

We do our best to ensure bugs don't creep up in our releases, but some may still slip through. If you encounter one while using the SDK, please create an issue in the tracker with the following information:

SDK version, Docker version and python version

pip freeze | grep docker && python --version && docker version

OS, distribution and OS version
The issue you're encountering including a stacktrace if applicable
If possible, steps or a code snippet to reproduce the issue

To save yourself time, please be sure to check our documentation and use the search function to find out if it has already been addressed, or is currently being looked at.

Submitting pull requests

Do you have a fix for an existing issue, or want to add a new functionality to the SDK? We happily welcome pull requests. Here are a few tips to make the review process easier on both the maintainers and yourself.

1. Sign your commits

Please refer to the “Sign your work” paragraph in the Docker contribution guidelines.

2. Make sure tests pass

Before we can review your pull request, please ensure that nothing has been broken by your changes by running the test suite. You can do so simply by running make test in the project root. This also includes coding style using flake8

3. Write clear, self-contained commits

Your commit message should be concise and describe the nature of the change. The commit itself should make sense in isolation from the others in your PR. Specifically, one should be able to review your commit separately from the context.

4. Rebase proactively

It's much easier to review a pull request that is up to date against the current master branch.

5. Notify thread subscribers when changes are made

GitHub doesn't notify subscribers when new commits happen on a PR, and fixes or additions might be missed. Please add a comment to the PR thread when you push new changes.

6. Two maintainers LGTM are required for merging

Please wait for review and approval of two maintainers, and respond to their comments and suggestions during review.

7. Add tests

Whether you're adding new functionality to the project or fixing a bug, please add relevant tests to ensure the code you added continues to work as the project evolves.

8. Add docs

This usually applies to new features rather than bug fixes, but new behavior should always be documented.

9. Ask questions

If you're ever confused about something pertaining to the project, feel free to reach out and ask questions. We will do our best to answer and help out.

Development environment

If you're looking contribute to Docker SDK for Python but are new to the project or Python, here are the steps to get you started.

Fork https://github.com/docker/docker-py to your username.
Clone your forked repository locally with git clone git@github.com:yourusername/docker-py.git.
Configure a remote for your fork so that you can sync changes you make with the original repository.
Enter the local directory cd docker-py.
Run python setup.py develop to install the dev version of the project and required dependencies. We recommend you do so inside a virtual environment

Running the tests & Code Quality

To get the source source code and run the unit tests, run:

$ git clone git://github.com/docker/docker-py.git
$ cd docker-py
$ make test

Building the docs

$ make docs
$ open _build/index.html

Release Checklist

Before a new release, please go through the following checklist:

Bump version in docker/version.py
Add a release note in docs/change_log.md
Git tag the version
Upload to pypi

Vulnerability Reporting

For any security issues, please do NOT file an issue or pull request on github! Please contact security@docker.com or read the Docker security page.