1Introduction 2============ 3 4liburing welcomes contributions, whether they be bug fixes, features, or 5documentation additions/updates. However, we do have some rules in place 6to govern the sanity of the project, and all contributions should follow 7the guidelines in this document. The main reasons for the rules are: 8 91) Keep the code consistent 102) Keep the git repository consistent 113) Maintain bisectability 12 13Coding style 14============ 15 16Generally, all the code in liburing should follow the same style. A few 17known exceptions exist, like syzbot test cases that got committed rather 18than re-writing them in a saner format. Any change you make, please 19follow the style of the code around you. 20 21Commit format 22============= 23 24Each commit should do one thing, and one thing only. If you find yourself, 25in the commit message, adding phrases like "Also do [...]" or "While in 26here [...]", then that's a sign that the change should have been split 27into multiple commits. If your change includes some refactoring of code to 28make your change possible, then that refactoring should be a separate 29commit, done first. That means this preparatory commit won't have any 30functional changes, and hence should be a no-op. It also means that your 31main commit, with the change that you actually care about, will be smaller 32and easier to review. 33 34Each commit must stand on its own in terms of what it provides, and how it 35works. Lots of changes are just a single commit, but for something a bit 36more involved, it's not uncommon to have a pull request contain multiple 37commits. Make each commit as simple as possible, and not any simpler. We'd 38much rather see 10 simple commits than 2 more complicated ones. If you 39stumble across something that needs fixing while making an unrelated 40change, then please make that change as a separate commit, explaining why 41it's being made. 42 43Each commit in a series must be buildable, it's not enough that the end 44result is buildable. See reason 3 in the introduction for why that's the 45case. 46 47No fixup commits! Sometimes people post a change and errors are pointed 48out in the commit, and the author then does a followup fix for that 49error. This isn't acceptable, please squash fixup commits into the 50commit that introduced the problem in the first place. This is done by 51amending the fix into the original commit that caused the issue. You can 52do that with git rebase -i <sha> and arrange the commit order such that 53the fixup is right after the original commit, and then use 's' (for 54squash) to squash the fixup into the original commit. Don't forget to 55edit the commit message while doing that, as git will combine the two 56commit messages into one. Or you can do it manually. Once done, force 57push your rewritten git history. See reasons 1-3 in the introduction 58series for why that is. 59 60Commit message 61============== 62 63A good commit explains the WHY of a commit - explain the reason for this 64commit to exist. Don't explain what the code in commit does, that should 65be readily apparent from just reading the code. If that isn't the case, 66then a comment in the code is going to be more useful than a lengthy 67explanation in the commit message. liburing commits use the following 68format: 69 70Title 71 72Body of commit 73 74Signed-off-by: ```My Identity <my@email.com>``` 75 76That is, a descriptive title on the first line, then an empty line, then 77the body of the commit message, then an empty line, and finally an SOB 78tag. The signed-off-by exists to provide proof of origin, see the 79[DCO](https://developercertificate.org/). 80 81Example commit: 82 83``` 84commit 0fe5c09195c0918f89582dd6ff098a58a0bdf62a 85Author: Jens Axboe <axboe@kernel.dk> 86Date: Fri Sep 6 15:54:04 2024 -0600 87 88 configure: fix ublk_cmd header check 89 90 The previous commit is mixing private structures and defines with public 91 uapi ones. Testing for UBLK_U_CMD_START_DEV is fine, CTRL_CMD_HAS_DATA 92 is not. And struct ublk_ctrl_cmd_data is not a public struct. 93 94 Fixes: 83bc535a3118 ("configure: don't enable ublk if modern commands not available") 95 Signed-off-by: Jens Axboe <axboe@kernel.dk> 96``` 97 98Since this change is pretty trivial, a huge explanation need not be given 99as to the reasonings for the change. However, for more complicated 100changes, better reasonings should be given. 101 102A Fixes line can be added if this commit fixes an issue in a previous 103commit. That kind of meta data can be useful down the line for finding 104dependencies between commits. Adding the following to your .gitconfig: 105 106``` 107[pretty] 108 fixes = Fixes: %h (\"%s\") 109``` 110 111and running ```git fixes <sha>``` will then generate the correctly 112formatted Fixes line for the commit. Likewise, other meta data can be: 113 114Link: https://somesite/somewhere 115 116can be useful to link to a discussion around the issue that led to this 117commit, perhaps a bug report. This can be a GitHub issue as well. If a 118commit closes/solves a GitHub issue, than: 119 120Closes: https://github.com/axboe/liburing/issues/XXXX 121 122can also be used. 123 124Each commit message should be formatted so each full line is 72-74 chars 125wide. For many of us, GitHub is not the primary location, and git log is 126often used in a terminal to browse the repo. Breaking lines at 72-74 127characters retains readability in an xterm/terminal. 128 129Pull Requests 130============= 131 132The git repository itself is the canonical location for information. It's 133quite fine to provide a lengthy explanation for a pull request on GitHub, 134however please ensure that this doesn't come at the expense of the commit 135messages themselves being lacking. The commit messages should stand on 136their own and contain everything that you'd otherwise put in the PR 137message. If you've worked on projects that send patches before, consider 138the PR message similar to the cover letter for a series of patches. 139 140Most contributors seem to use GH for sending patches, which is fine. If 141you prefer using email, then patches can also be sent to the io_uring 142mailing list: io-uring@vger.kernel.org. 143 144liburing doesn't squash/rebase-on-merge, or other heinous practices 145sometimes seen elsewhere. Whatever sha your commit has in your tree is 146what it'll have in the upstream tree. Patches are applied directly, and 147pull requests are merged with a merge commit. If meta data needs to go 148into the merge commit, then it will go into the merge commit message. 149This means that you don't need to continually rebase your changes on top 150of the master branch. 151 152Testing changes 153=============== 154 155You should ALWAYS test your changes, no matter how trivial or obviously 156correct they may seem. Nobody is infallible, and making mistakes is only 157human. 158 159liburing contains a wide variety of functional tests. If you make changes 160to liburing, then you should run the test cases. This is done by building 161the repo and running ```make runtests```. Note that some of the liburing 162tests test for defects in older kernels, and hence it's possible that they 163will crash on an outdated kernel that doesn't contain fixes from the 164stable kernel tree. If in doubt, building and running the tests in a vm is 165encouraged. 166