1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
# Contributing guidelines
See the [Docker contributing guidelines](https://github.com/docker/docker/blob/master/CONTRIBUTING.md).
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](https://github.com/docker/docker-py/issues/new) 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](https://docker-py.readthedocs.io/) and use the
[search function](https://github.com/docker/docker-py/search) 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"](https://github.com/docker/docker/blob/master/CONTRIBUTING.md#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.
1. Fork https://github.com/docker/docker-py to your username.
2. Clone your forked repository locally with
`git clone git@github.com:yourusername/docker-py.git`.
3. Configure a
[remote](https://help.github.com/articles/configuring-a-remote-for-a-fork/)
for your fork so that you can
[sync changes you make](https://help.github.com/articles/syncing-a-fork/)
with the original repository.
4. Enter the local directory `cd docker-py`.
5. 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](http://docs.python-guide.org/en/latest/dev/virtualenvs)
## 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](mailto:security@docker.com) or read [the
Docker security page](https://www.docker.com/resources/security/).
|
