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