github.com/containers/podman/v5@v5.1.0-rc1/CONTRIBUTING.md (about) 1  2 # Contributing to Podman 3 4 We'd love to have you join the community! Below summarizes the processes 5 that we follow. 6 7 ## Topics 8 9 * [Reporting Issues](#reporting-issues) 10 * [Working On Issues](#working-on-issues) 11 * [Contributing to Podman](#contributing-to-podman) 12 * [Continuous Integration](#continuous-integration) [](https://cirrus-ci.com/github/containers/podman/master) 13 * [Submitting Pull Requests](#submitting-pull-requests) 14 * [Communications](#communications) 15 16 ## Reporting Issues 17 18 Before reporting an issue, check our backlog of 19 [open issues](https://github.com/containers/podman/issues) 20 to see if someone else has already reported it. If so, feel free to add 21 your scenario, or additional information, to the discussion. Or simply 22 "subscribe" to it to be notified when it is updated. 23 24 Note: Older closed issues/PRs are automatically locked, if you have a similar 25 problem please open a new issue instead of commenting. 26 27 If you find a new issue with the project we'd love to hear about it! The most 28 important aspect of a bug report is that it includes enough information for 29 us to reproduce it. To make this easier, there are three types of issue 30 templates you can use, if you have a bug to report, please use *Bug Report* 31 template or if you have an idea to propose, please use the *Feature Request* 32 template or if your issue is something else, please use the default template. 33 Please include as much detail as possible and try to remove the extra stuff 34 that doesn't really relate to the issue itself. The easier it is for us to 35 reproduce it, the faster it'll be fixed! 36 37 Please don't include any private/sensitive information in your issue! 38 39 ## Working On Issues 40 41 Once you have decided to contribute to Podman by working on an issue, check our 42 backlog of [open issues](https://github.com/containers/podman/issues) looking 43 for any that do not have an "In Progress" label attached to it. Often issues 44 will be assigned to someone, to be worked on at a later time. If you have the 45 time to work on the issue now add yourself as an assignee, and set the 46 "In Progress" label if you’re a member of the “Containers” GitHub organization. 47 If you can not set the label, just add a quick comment in the issue asking that 48 the “In Progress” label be set and a member will do so for you. 49 50 ## Contributing to Podman 51 52 This section describes how to start a contribution to Podman. These instructions are geared towards using a Linux development machine, which is required for doing development on the Podman backend. Check out these instructions for building the Podman client on [MacOSX](./build_osx.md) or 53 [Windows](./build_windows.md). 54 55 ### Prepare your environment 56 57 Read the [install documentation to see how to install dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies). 58 59 The install documentation will illustrate the following steps: 60 - install libs and tools 61 - check installed versions 62 - configure network 63 - how to install Podman from sources 64 65 ### Fork and clone Podman 66 67 First you need to fork this project on GitHub. 68 69 Be sure to have [defined your `$GOPATH` environment variable](https://github.com/golang/go/wiki/GOPATH). 70 71 Create a path that corresponds to the go import paths of Podman: `mkdir -p $GOPATH/src/github.com/containers`. 72 73 Then clone your fork locally: 74 ```shell 75 $ git clone git@github.com:<you>/podman $GOPATH/src/github.com/containers/podman 76 $ cd $GOPATH/src/github.com/containers/podman 77 ``` 78 79 ### Deal with make 80 81 Podman uses a Makefile to realize common actions like building etc... 82 83 You can list available actions by using: 84 ```shell 85 $ make help 86 Usage: make <target> 87 ...output... 88 ``` 89 90 ### Install tools 91 92 Makefile allow you to install needed tools: 93 ```shell 94 $ make install.tools 95 ``` 96 97 ### Building binaries and test your changes 98 99 To test your changes do `make binaries` to generate your binaries. 100 101 Your binaries are created inside the `bin/` directory and you can test your changes: 102 ```shell 103 $ bin/podman --help 104 bin/podman --help 105 NAME: 106 podman - manage pods and images 107 108 USAGE: 109 podman [global options] command [command options] [arguments...] 110 111 VERSION: 112 1.0.1-dev 113 114 COMMANDS: 115 attach Attach to a running container 116 build Build an image using instructions from Dockerfiles 117 commit Create new image based on the changed container 118 container Manage Containers 119 cp Copy files/folders between a container and the local filesystem 120 ``` 121 122 Well, you can now create your own branch, apply changes on it, and then submitting your pull request. 123 124 For further reading about branching [you can read this document](https://herve.beraud.io/containers/linux/podman/isolate/environment/2019/02/06/how-to-hack-on-podman.html). 125 126 ## Documentation 127 128 Make sure to update the documentation if needed. You can find the man pages under `docs/source/markdown`. The syntax for the formatting of all man pages can be found [here](docs/MANPAGE_SYNTAX.md). 129 130 ## Submitting Pull Requests 131 132 No Pull Request (PR) is too small! Typos, additional comments in the code, 133 new test cases, bug fixes, new features, more documentation, ... it's all 134 welcome! 135 136 While bug fixes can first be identified via an "issue", that is not required. 137 It's ok to just open up a PR with the fix, but make sure you include the same 138 information you would have included in an issue - like how to reproduce it. 139 140 PRs for new features should include some background on what use cases the 141 new code is trying to address. When possible and when it makes sense, try to break-up 142 larger PRs into smaller ones - it's easier to review smaller 143 code changes. But only if those smaller ones make sense as stand-alone PRs. 144 145 Regardless of the type of PR, all PRs should include: 146 * well documented code changes. 147 * additional testcases. Ideally, they should fail w/o your code change applied. 148 (With a few exceptions, CI hooks will block your PR unless your change 149 includes files named `*_test.go` or under the `test/` subdirectory. Repo 150 admins may bypass this restriction by setting the 'No New Tests' GitHub 151 label on the PR). 152 * documentation changes. 153 154 Squash your commits into logical pieces of work that might want to be reviewed 155 separate from the rest of the PRs. But, squashing down to just one commit is ok 156 too since in the end the entire PR will be reviewed anyway. When in doubt, 157 squash. 158 159 PRs that fix issues should include a reference like `Closes #XXXX` in the 160 commit message so that GitHub will automatically close the referenced issue 161 when the PR is merged. 162 163 PRs will be approved by an [approver][owners] listed in [`OWNERS`](OWNERS). 164 165 In case you're only changing docs, make sure to prefix the PR title with 166 "[CI:DOCS]". That will prevent functional tests from running and save time and 167 energy. 168 169 ### Describe your Changes in Commit Messages 170 171 Describe your problem. Whether your patch is a one-line bug fix or 5000 lines 172 of a new feature, there must be an underlying problem that motivated you to do 173 this work. Convince the reviewer that there is a problem worth fixing and that 174 it makes sense for them to read past the first paragraph. 175 176 Describe user-visible impact. Straight up crashes and lockups are pretty 177 convincing, but not all bugs are that blatant. Even if the problem was spotted 178 during code review, describe the impact you think it can have on users. Keep in 179 mind that the majority of users run packages provided by distributions, so 180 include anything that could help route your change downstream. 181 182 Quantify optimizations and trade-offs. If you claim improvements in 183 performance, memory consumption, stack footprint, or binary size, include 184 numbers that back them up. But also describe non-obvious costs. Optimizations 185 usually aren’t free but trade-offs between CPU, memory, and readability; or, 186 when it comes to heuristics, between different workloads. Describe the expected 187 downsides of your optimization so that the reviewer can weigh costs against 188 benefits. 189 190 Once the problem is established, describe what you are actually doing about it 191 in technical detail. It’s important to describe the change in plain English for 192 the reviewer to verify that the code is behaving as you intend it to. 193 194 Solve only one problem per patch. If your description starts to get long, 195 that’s a sign that you probably need to split up your patch. 196 197 If the patch fixes a logged bug entry, refer to that bug entry by number and 198 URL. If the patch follows from a mailing list discussion, give a URL to the 199 mailing list archive. 200 201 However, try to make your explanation understandable without external 202 resources. In addition to giving a URL to a mailing list archive or bug, 203 summarize the relevant points of the discussion that led to the patch as 204 submitted. 205 206 If you want to refer to a specific commit, don’t just refer to the SHA-1 ID of 207 the commit. Please also include the oneline summary of the commit, to make it 208 easier for reviewers to know what it is about. Example: 209 210 ``` 211 Commit f641c2d9384e ("fix bug in rm -fa parallel deletes") [...] 212 ``` 213 214 You should also be sure to use at least the first twelve characters of the 215 SHA-1 ID. The Podman repository holds a lot of objects, making collisions with 216 shorter IDs a real possibility. Bear in mind that, even if there is no 217 collision with your six-character ID now, that condition may change five years 218 from now. 219 220 If your patch fixes a bug in a specific commit, e.g. you found an issue using 221 git bisect, please use the ‘Fixes:’ tag with the first 12 characters of the 222 SHA-1 ID, and the one line summary. For example: 223 224 ``` 225 Fixes: f641c2d9384e ("fix bug in rm -fa parallel deletes") 226 ``` 227 228 The following git config settings can be used to add a pretty format for 229 outputting the above style in the git log or git show commands: 230 231 ``` 232 [core] 233 abbrev = 12 234 [pretty] 235 fixes = Fixes: %h (\"%s\") 236 ``` 237 238 ### Sign your PRs 239 240 The sign-off is a line at the end of the explanation for the patch. Your 241 signature certifies that you wrote the patch or otherwise have the right to pass 242 it on as an open-source patch. The rules are simple: if you can certify 243 the below (from [developercertificate.org](https://developercertificate.org/)): 244 245 ``` 246 Developer Certificate of Origin 247 Version 1.1 248 249 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 250 660 York Street, Suite 102, 251 San Francisco, CA 94110 USA 252 253 Everyone is permitted to copy and distribute verbatim copies of this 254 license document, but changing it is not allowed. 255 256 Developer's Certificate of Origin 1.1 257 258 By making a contribution to this project, I certify that: 259 260 (a) The contribution was created in whole or in part by me and I 261 have the right to submit it under the open source license 262 indicated in the file; or 263 264 (b) The contribution is based upon previous work that, to the best 265 of my knowledge, is covered under an appropriate open source 266 license and I have the right under that license to submit that 267 work with modifications, whether created in whole or in part 268 by me, under the same open source license (unless I am 269 permitted to submit under a different license), as indicated 270 in the file; or 271 272 (c) The contribution was provided directly to me by some other 273 person who certified (a), (b) or (c) and I have not modified 274 it. 275 276 (d) I understand and agree that this project and the contribution 277 are public and that a record of the contribution (including all 278 personal information I submit with it, including my sign-off) is 279 maintained indefinitely and may be redistributed consistent with 280 this project or the open source license(s) involved. 281 ``` 282 283 Then you just add a line to every git commit message: 284 285 Signed-off-by: Joe Smith <joe.smith@email.com> 286 287 Use your real name (sorry, no pseudonyms or anonymous contributions.) 288 289 If you set your `user.name` and `user.email` git configs, you can sign your 290 commit automatically with `git commit -s`. 291 292 ### Go Format and lint 293 294 All code changes must pass ``make validatepr``. 295 296 ### Integration Tests 297 298 Our primary means of performing integration testing for Podman is with the 299 [Ginkgo](https://github.com/onsi/ginkgo) BDD testing framework. This allows 300 us to use native Golang to perform our tests and there is a strong affiliation 301 between Ginkgo and the Go test framework. Adequate test cases are expected to 302 be provided with PRs. 303 304 For details on how to run the tests for Podman in your test environment, see the 305 testing [README.md](test/README.md). 306 307 ## Continuous Integration 308 309 All pull requests and branch-merges automatically run: 310 311 * Go format/lint checking 312 * Unit testing 313 * Integration Testing 314 * Special testing (like running inside a container, or as a regular user) 315 316 There is always additional complexity added by automation, and so it sometimes 317 can fail for any number of reasons. This includes post-merge testing on all 318 branches, which you may occasionally see [red bars on the status graph 319 .](https://cirrus-ci.com/github/containers/podman/master) 320 321 When the graph shows mostly green bars on the right, it's a good indication 322 the main branch is currently stable. Alternating red/green bars is indicative 323 of a testing "flake", and should be examined (anybody can do this): 324 325 * *One or a small handful of tests, on a single task, (i.e. specific distro/version) 326 where all others ran successfully:* Frequently the cause is networking or a brief 327 external service outage. The failed tasks may simply be re-run by pressing the 328 corresponding button on the task details page. 329 330 * *Multiple tasks failing*: Logically this should be due to some shared/common element. 331 If that element is identifiable as a networking or external service (e.g. packaging 332 repository outage), a re-run should be attempted. 333 334 * *All tasks are failing*: If a common element is **not** identifiable as 335 temporary (i.e. container registry outage), please seek assistance via 336 [the methods below](#communications) as this may be early indication of 337 a more serious problem. 338 339 In the (hopefully) rare case there are multiple, contiguous red bars, this is 340 a ***very bad*** sign. It means additional merges are occurring despite an uncorrected 341 or persistently faulty condition. This risks additional bugs being introduced 342 and further complication of necessary corrective measures. Most likely people 343 are aware and working on this, but it doesn't hurt [to confirm and/or try and help 344 if possible.](#communications) 345 346 ## Communications 347 348 For general questions and discussion, please use the 349 IRC `#podman` channel on `irc.libera.chat`. 350 351 For discussions around issues/bugs and features, you can use the GitHub 352 [issues](https://github.com/containers/podman/issues) 353 and 354 [PRs](https://github.com/containers/podman/pulls) 355 tracking system. 356 357 There is also a [mailing list](https://lists.podman.io/archives/) at `lists.podman.io`. 358 You can subscribe by sending a message to `podman@lists.podman.io` with the subject `subscribe`. 359 360 ### Bot Interactions 361 362 The primary human-interface is through comments in pull-requests. Some of these are outlined 363 below, along with their meaning and intended usage. Some of them require the comment 364 author hold special privileges on the github repository. Others can be used by anyone. 365 366 * ``/close``: Closes an issue or PR. 367 368 * ``/approve``: Mark a PR as appropriate to the project, and as close to meeting 369 met all the contribution criteria above. Adds the *approved* label, marking 370 it as ready for review and possible future merging. 371 372 * ``/lgtm``: A literal "Stamp of approval", signaling okay-to-merge. This causes 373 the bot to ad the *lgtm* label, then attempt a merge. In other words - Never, 374 ever, ever comment ``/lgtm``, unless a PR has actually, really, been fully 375 reviewed. The bot isn't too smart about these things, and could merge 376 unintentionally. Instead, just write ``LGTM``, or 377 spell it out. 378 379 * ``/hold`` and ``/unhold``: Override the automatic handling of a request. Either 380 put it on hold (no handling) or remove the hold (normal handling). 381 382 * ``[ci skip]``: [Adding `[ci skip]` within the HEAD commit](https://cirrus-ci.org/guide/writing-tasks/#conditional-task-execution) 383 will cause Cirrus CI to ***NOT*** execute tests for the PR or after merge. This 384 is useful in only one instance: Your changes are absolutely not exercised by 385 any test. For example, documentation changes. ***IMPORTANT NOTE*** **Other 386 automation may interpret the lack of test results as "PASSED" and unintentional 387 merge a PR. Consider also using `/hold` in a comment, to add additional 388 protection.** 389 390 [The complete list may be found on the command-help page.](https://prow.k8s.io/command-help) 391 However, not all commands are implemented for this repository. If in doubt, ask a maintainer.