github.com/containers/podman/v4@v4.9.4/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 ### Prerequisite before build 98 99 You need install some dependencies before building a binary. 100 101 #### Fedora 102 103 ```shell 104 $ sudo dnf install gpgme-devel libseccomp-devel.x86_64 systemd-devel 105 $ export PKG_CONFIG_PATH="/usr/lib/pkgconfig" 106 ``` 107 108 #### Debian / Ubuntu 109 110 ```shell 111 $ sudo apt-get install -y libsystemd-dev libgpgme-dev libseccomp-dev 112 $ export PKG_CONFIG_PATH="/usr/lib/pkgconfig" 113 ``` 114 115 ### Building binaries and test your changes 116 117 To test your changes do `make binaries` to generate your binaries. 118 119 Your binaries are created inside the `bin/` directory and you can test your changes: 120 ```shell 121 $ bin/podman --help 122 bin/podman --help 123 NAME: 124 podman - manage pods and images 125 126 USAGE: 127 podman [global options] command [command options] [arguments...] 128 129 VERSION: 130 1.0.1-dev 131 132 COMMANDS: 133 attach Attach to a running container 134 build Build an image using instructions from Dockerfiles 135 commit Create new image based on the changed container 136 container Manage Containers 137 cp Copy files/folders between a container and the local filesystem 138 ``` 139 140 Well, you can now create your own branch, apply changes on it, and then submitting your pull request. 141 142 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). 143 144 ## Documentation 145 146 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). 147 148 ## Submitting Pull Requests 149 150 No Pull Request (PR) is too small! Typos, additional comments in the code, 151 new test cases, bug fixes, new features, more documentation, ... it's all 152 welcome! 153 154 While bug fixes can first be identified via an "issue", that is not required. 155 It's ok to just open up a PR with the fix, but make sure you include the same 156 information you would have included in an issue - like how to reproduce it. 157 158 PRs for new features should include some background on what use cases the 159 new code is trying to address. When possible and when it makes sense, try to break-up 160 larger PRs into smaller ones - it's easier to review smaller 161 code changes. But only if those smaller ones make sense as stand-alone PRs. 162 163 Regardless of the type of PR, all PRs should include: 164 * well documented code changes. 165 * additional testcases. Ideally, they should fail w/o your code change applied. 166 (With a few exceptions, CI hooks will block your PR unless your change 167 includes files named `*_test.go` or under the `test/` subdirectory. To 168 bypass this block, include the string `[NO NEW TESTS NEEDED]` in your 169 commit message). 170 * documentation changes. 171 172 Squash your commits into logical pieces of work that might want to be reviewed 173 separate from the rest of the PRs. But, squashing down to just one commit is ok 174 too since in the end the entire PR will be reviewed anyway. When in doubt, 175 squash. 176 177 PRs that fix issues should include a reference like `Closes #XXXX` in the 178 commit message so that GitHub will automatically close the referenced issue 179 when the PR is merged. 180 181 PRs will be approved by an [approver][owners] listed in [`OWNERS`](OWNERS). 182 183 In case you're only changing docs, make sure to prefix the PR title with 184 "[CI:DOCS]". That will prevent functional tests from running and save time and 185 energy. 186 187 ### Describe your Changes in Commit Messages 188 189 Describe your problem. Whether your patch is a one-line bug fix or 5000 lines 190 of a new feature, there must be an underlying problem that motivated you to do 191 this work. Convince the reviewer that there is a problem worth fixing and that 192 it makes sense for them to read past the first paragraph. 193 194 Describe user-visible impact. Straight up crashes and lockups are pretty 195 convincing, but not all bugs are that blatant. Even if the problem was spotted 196 during code review, describe the impact you think it can have on users. Keep in 197 mind that the majority of users run packages provided by distributions, so 198 include anything that could help route your change downstream. 199 200 Quantify optimizations and trade-offs. If you claim improvements in 201 performance, memory consumption, stack footprint, or binary size, include 202 numbers that back them up. But also describe non-obvious costs. Optimizations 203 usually aren’t free but trade-offs between CPU, memory, and readability; or, 204 when it comes to heuristics, between different workloads. Describe the expected 205 downsides of your optimization so that the reviewer can weigh costs against 206 benefits. 207 208 Once the problem is established, describe what you are actually doing about it 209 in technical detail. It’s important to describe the change in plain English for 210 the reviewer to verify that the code is behaving as you intend it to. 211 212 Solve only one problem per patch. If your description starts to get long, 213 that’s a sign that you probably need to split up your patch. 214 215 If the patch fixes a logged bug entry, refer to that bug entry by number and 216 URL. If the patch follows from a mailing list discussion, give a URL to the 217 mailing list archive. 218 219 However, try to make your explanation understandable without external 220 resources. In addition to giving a URL to a mailing list archive or bug, 221 summarize the relevant points of the discussion that led to the patch as 222 submitted. 223 224 If you want to refer to a specific commit, don’t just refer to the SHA-1 ID of 225 the commit. Please also include the oneline summary of the commit, to make it 226 easier for reviewers to know what it is about. Example: 227 228 ``` 229 Commit f641c2d9384e ("fix bug in rm -fa parallel deletes") [...] 230 ``` 231 232 You should also be sure to use at least the first twelve characters of the 233 SHA-1 ID. The Podman repository holds a lot of objects, making collisions with 234 shorter IDs a real possibility. Bear in mind that, even if there is no 235 collision with your six-character ID now, that condition may change five years 236 from now. 237 238 If your patch fixes a bug in a specific commit, e.g. you found an issue using 239 git bisect, please use the ‘Fixes:’ tag with the first 12 characters of the 240 SHA-1 ID, and the one line summary. For example: 241 242 ``` 243 Fixes: f641c2d9384e ("fix bug in rm -fa parallel deletes") 244 ``` 245 246 The following git config settings can be used to add a pretty format for 247 outputting the above style in the git log or git show commands: 248 249 ``` 250 [core] 251 abbrev = 12 252 [pretty] 253 fixes = Fixes: %h (\"%s\") 254 ``` 255 256 ### Sign your PRs 257 258 The sign-off is a line at the end of the explanation for the patch. Your 259 signature certifies that you wrote the patch or otherwise have the right to pass 260 it on as an open-source patch. The rules are simple: if you can certify 261 the below (from [developercertificate.org](https://developercertificate.org/)): 262 263 ``` 264 Developer Certificate of Origin 265 Version 1.1 266 267 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 268 660 York Street, Suite 102, 269 San Francisco, CA 94110 USA 270 271 Everyone is permitted to copy and distribute verbatim copies of this 272 license document, but changing it is not allowed. 273 274 Developer's Certificate of Origin 1.1 275 276 By making a contribution to this project, I certify that: 277 278 (a) The contribution was created in whole or in part by me and I 279 have the right to submit it under the open source license 280 indicated in the file; or 281 282 (b) The contribution is based upon previous work that, to the best 283 of my knowledge, is covered under an appropriate open source 284 license and I have the right under that license to submit that 285 work with modifications, whether created in whole or in part 286 by me, under the same open source license (unless I am 287 permitted to submit under a different license), as indicated 288 in the file; or 289 290 (c) The contribution was provided directly to me by some other 291 person who certified (a), (b) or (c) and I have not modified 292 it. 293 294 (d) I understand and agree that this project and the contribution 295 are public and that a record of the contribution (including all 296 personal information I submit with it, including my sign-off) is 297 maintained indefinitely and may be redistributed consistent with 298 this project or the open source license(s) involved. 299 ``` 300 301 Then you just add a line to every git commit message: 302 303 Signed-off-by: Joe Smith <joe.smith@email.com> 304 305 Use your real name (sorry, no pseudonyms or anonymous contributions.) 306 307 If you set your `user.name` and `user.email` git configs, you can sign your 308 commit automatically with `git commit -s`. 309 310 ### Go Format and lint 311 312 All code changes must pass ``make validate`` and ``make lint``. 313 314 ``` 315 podman build -t gate -f contrib/gate/Dockerfile . 316 ``` 317 318 ***N/B:*** **don't miss the dot (.) at the end, it's really important** 319 320 ### Integration Tests 321 322 Our primary means of performing integration testing for Podman is with the 323 [Ginkgo](https://github.com/onsi/ginkgo) BDD testing framework. This allows 324 us to use native Golang to perform our tests and there is a strong affiliation 325 between Ginkgo and the Go test framework. Adequate test cases are expected to 326 be provided with PRs. 327 328 For details on how to run the tests for Podman in your test environment, see the 329 testing [README.md](test/README.md). 330 331 ## Continuous Integration 332 333 All pull requests and branch-merges automatically run: 334 335 * Go format/lint checking 336 * Unit testing 337 * Integration Testing 338 * Special testing (like running inside a container, or as a regular user) 339 340 There is always additional complexity added by automation, and so it sometimes 341 can fail for any number of reasons. This includes post-merge testing on all 342 branches, which you may occasionally see [red bars on the status graph 343 .](https://cirrus-ci.com/github/containers/podman/master) 344 345 When the graph shows mostly green bars on the right, it's a good indication 346 the main branch is currently stable. Alternating red/green bars is indicative 347 of a testing "flake", and should be examined (anybody can do this): 348 349 * *One or a small handful of tests, on a single task, (i.e. specific distro/version) 350 where all others ran successfully:* Frequently the cause is networking or a brief 351 external service outage. The failed tasks may simply be re-run by pressing the 352 corresponding button on the task details page. 353 354 * *Multiple tasks failing*: Logically this should be due to some shared/common element. 355 If that element is identifiable as a networking or external service (e.g. packaging 356 repository outage), a re-run should be attempted. 357 358 * *All tasks are failing*: If a common element is **not** identifiable as 359 temporary (i.e. container registry outage), please seek assistance via 360 [the methods below](#communications) as this may be early indication of 361 a more serious problem. 362 363 In the (hopefully) rare case there are multiple, contiguous red bars, this is 364 a ***very bad*** sign. It means additional merges are occurring despite an uncorrected 365 or persistently faulty condition. This risks additional bugs being introduced 366 and further complication of necessary corrective measures. Most likely people 367 are aware and working on this, but it doesn't hurt [to confirm and/or try and help 368 if possible.](#communications) 369 370 ## Communications 371 372 For general questions and discussion, please use the 373 IRC `#podman` channel on `irc.libera.chat`. 374 375 For discussions around issues/bugs and features, you can use the GitHub 376 [issues](https://github.com/containers/podman/issues) 377 and 378 [PRs](https://github.com/containers/podman/pulls) 379 tracking system. 380 381 There is also a [mailing list](https://lists.podman.io/archives/) at `lists.podman.io`. 382 You can subscribe by sending a message to `podman@lists.podman.io` with the subject `subscribe`. 383 384 ### Bot Interactions 385 386 The primary human-interface is through comments in pull-requests. Some of these are outlined 387 below, along with their meaning and intended usage. Some of them require the comment 388 author hold special privileges on the github repository. Others can be used by anyone. 389 390 * ``/close``: Closes an issue or PR. 391 392 * ``/approve``: Mark a PR as appropriate to the project, and as close to meeting 393 met all the contribution criteria above. Adds the *approved* label, marking 394 it as ready for review and possible future merging. 395 396 * ``/lgtm``: A literal "Stamp of approval", signaling okay-to-merge. This causes 397 the bot to ad the *lgtm* label, then attempt a merge. In other words - Never, 398 ever, ever comment ``/lgtm``, unless a PR has actually, really, been fully 399 reviewed. The bot isn't too smart about these things, and could merge 400 unintentionally. Instead, just write ``LGTM``, or 401 spell it out. 402 403 * ``/hold`` and ``/unhold``: Override the automatic handling of a request. Either 404 put it on hold (no handling) or remove the hold (normal handling). 405 406 * ``[ci skip]``: [Adding `[ci skip]` within the HEAD commit](https://cirrus-ci.org/guide/writing-tasks/#conditional-task-execution) 407 will cause Cirrus CI to ***NOT*** execute tests for the PR or after merge. This 408 is useful in only one instance: Your changes are absolutely not exercised by 409 any test. For example, documentation changes. ***IMPORTANT NOTE*** **Other 410 automation may interpret the lack of test results as "PASSED" and unintentional 411 merge a PR. Consider also using `/hold` in a comment, to add additional 412 protection.** 413 414 [The complete list may be found on the command-help page.](https://prow.k8s.io/command-help) 415 However, not all commands are implemented for this repository. If in doubt, ask a maintainer.