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