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