CONTRIBUTE.md (16089B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 # Contributing to the curl project 8 9 This document is intended to offer guidelines on how to best contribute to the 10 curl project. This concerns new features as well as corrections to existing 11 flaws or bugs. 12 13 ## Join the Community 14 15 Skip over to [https://curl.se/mail/](https://curl.se/mail/) and join 16 the appropriate mailing list(s). Read up on details before you post 17 questions. Read this file before you start sending patches. We prefer 18 questions sent to and discussions being held on the mailing list(s), not sent 19 to individuals. 20 21 Before posting to one of the curl mailing lists, please read up on the 22 [mailing list etiquette](https://curl.se/mail/etiquette.html). 23 24 We also hang out on IRC in #curl on libera.chat 25 26 If you are at all interested in the code side of things, consider clicking 27 'watch' on the [curl repository on GitHub](https://github.com/curl/curl) to be 28 notified of pull requests and new issues posted there. 29 30 ## License and copyright 31 32 When contributing with code, you agree to put your changes and new code under 33 the same license curl and libcurl is already using unless stated and agreed 34 otherwise. 35 36 If you add a larger piece of code, you can opt to make that file or set of 37 files to use a different license as long as they do not enforce any changes to 38 the rest of the package and they make sense. Such "separate parts" can not be 39 GPL licensed (as we do not want copyleft to affect users of libcurl) but they 40 must use "GPL compatible" licenses (as we want to allow users to use libcurl 41 properly in GPL licensed environments). 42 43 When changing existing source code, you do not alter the copyright of the 44 original file(s). The copyright is still owned by the original creator(s) or 45 those who have been assigned copyright by the original author(s). 46 47 By submitting a patch to the curl project, you are assumed to have the right 48 to the code and to be allowed by your employer or whatever to hand over that 49 patch/code to us. We credit you for your changes as far as possible, to give 50 credit but also to keep a trace back to who made what changes. Please always 51 provide us with your full real name when contributing, 52 53 ## What To Read 54 55 Source code, the man pages, the [INTERNALS 56 document](https://curl.se/dev/internals.html), 57 [TODO](https://curl.se/docs/todo.html), 58 [KNOWN_BUGS](https://curl.se/docs/knownbugs.html) and the [most recent 59 changes](https://curl.se/dev/sourceactivity.html) in git. Just lurking on the 60 [curl-library mailing list](https://curl.se/mail/list.cgi?list=curl-library) 61 gives you a lot of insights on what's going on right now. Asking there is a 62 good idea too. 63 64 ## Write a good patch 65 66 ### Follow code style 67 68 When writing C code, follow the 69 [CODE_STYLE](https://curl.se/dev/code-style.html) already established in 70 the project. Consistent style makes code easier to read and mistakes less 71 likely to happen. Run `make checksrc` before you submit anything, to make sure 72 you follow the basic style. That script does not verify everything, but if it 73 complains you know you have work to do. 74 75 ### Non-clobbering All Over 76 77 When you write new functionality or fix bugs, it is important that you do not 78 fiddle all over the source files and functions. Remember that it is likely 79 that other people have done changes in the same source files as you have and 80 possibly even in the same functions. If you bring completely new 81 functionality, try writing it in a new source file. If you fix bugs, try to 82 fix one bug at a time and send them as separate patches. 83 84 ### Write Separate Changes 85 86 It is annoying when you get a huge patch from someone that is said to fix 11 87 odd problems, but discussions and opinions do not agree with 10 of them - or 9 88 of them were already fixed in a different way. Then the person merging this 89 change needs to extract the single interesting patch from somewhere within the 90 huge pile of source, and that creates a lot of extra work. 91 92 Preferably, each fix that corrects a problem should be in its own patch/commit 93 with its own description/commit message stating exactly what they correct so 94 that all changes can be selectively applied by the maintainer or other 95 interested parties. 96 97 Also, separate changes enable bisecting much better for tracking problems 98 and regression in the future. 99 100 ### Patch Against Recent Sources 101 102 Please try to get the latest available sources to make your patches against. 103 It makes the lives of the developers so much easier. The best is if you get 104 the most up-to-date sources from the git repository, but the latest release 105 archive is quite OK as well. 106 107 ### Documentation 108 109 Writing docs is dead boring and one of the big problems with many open source 110 projects but someone's gotta do it. It makes things a lot easier if you submit 111 a small description of your fix or your new features with every contribution 112 so that it can be swiftly added to the package documentation. 113 114 Documentation is mostly provided as manpages or plain ASCII files. The 115 manpages are rendered from their source files that are usually written using 116 markdown. Most HTML files on the website and in the release archives are 117 generated from corresponding markdown and ASCII files. 118 119 ### Test Cases 120 121 Since the introduction of the test suite, we can quickly verify that the main 122 features are working as they are supposed to. To maintain this situation and 123 improve it, all new features and functions that are added need to be tested in 124 the test suite. Every feature that is added should get at least one valid test 125 case that verifies that it works as documented. If every submitter also posts 126 a few test cases, it does not end up a heavy burden on a single person. 127 128 If you do not have test cases or perhaps you have done something that is hard 129 to write tests for, do explain exactly how you have otherwise tested and 130 verified your changes. 131 132 # Submit Your Changes 133 134 ## Get your changes merged 135 136 Ideally you file a [pull request on 137 GitHub](https://github.com/curl/curl/pulls), but you can also send your plain 138 patch to [the curl-library mailing 139 list](https://curl.se/mail/list.cgi?list=curl-library). 140 141 If you opt to post a patch on the mailing list, chances are someone converts 142 it into a pull request for you, to have the CI jobs verify it proper before it 143 can be merged. Be prepared that some feedback on the proposed change might 144 then come on GitHub. 145 146 Your changes be reviewed and discussed and you are expected to correct flaws 147 pointed out and update accordingly, or the change risks stalling and 148 eventually just getting deleted without action. As a submitter of a change, 149 you are the owner of that change until it has been merged. 150 151 Respond on the list or on GitHub about the change and answer questions and/or 152 fix nits/flaws. This is important. We take lack of replies as a sign that you 153 are not anxious to get your patch accepted and we tend to simply drop such 154 changes. 155 156 ## About pull requests 157 158 With GitHub it is easy to send a [pull 159 request](https://github.com/curl/curl/pulls) to the curl project to have 160 changes merged. 161 162 We strongly prefer pull requests to mailed patches, as it makes it a proper 163 git commit that is easy to merge and they are easy to track and not that easy 164 to lose in the flood of many emails, like they sometimes do on the mailing 165 lists. 166 167 Every pull request submitted is automatically tested in several different 168 ways. [See the CI document for more 169 information](https://github.com/curl/curl/blob/master/docs/tests/CI.md). 170 171 Sometimes the tests fail due to a dependency service temporarily being offline 172 or otherwise unavailable, e.g. package downloads. In this case you can just 173 try to update your pull requests to rerun the tests later as described below. 174 175 You can update your pull requests by pushing new commits or force-pushing 176 changes to existing commits. Force-pushing an amended commit without any 177 actual content changed also allows you to retrigger the tests for that commit. 178 179 When you adjust your pull requests after review, consider squashing the 180 commits so that we can review the full updated version more easily. 181 182 A pull request sent to the project might get labeled `needs-votes` by a 183 project maintainer. This label means that in addition to meeting all other 184 checks and qualifications this pull request must also receive more "votes" of 185 user support. More signs that people want this to happen. It could be in the 186 form of messages saying so, or thumbs-up reactions on GitHub. 187 188 ## When the pull request is approved 189 190 If it does not seem to get approved when you think it is ready - feel free to 191 ask for approval. 192 193 Once your pull request has been approved it can be merged by a maintainer. 194 195 For new features, or changes, we require that the *feature window* is open for 196 the pull request to be merged. This is typically a three week period that 197 starts ten days after a previous release. New features submitted as pull 198 requests while the window is closed simply have to wait until it opens to get 199 merged. 200 201 If time passes without your approved pull request gets merged: feel free to 202 ask what more you can do to make it happen. 203 204 ## Making quality changes 205 206 Make the patch against as recent source versions as possible. 207 208 If you have followed the tips in this document and your patch still has not 209 been incorporated or responded to after some weeks, consider resubmitting it 210 to the list or better yet: change it to a pull request. 211 212 ## Commit messages 213 214 How to write git commit messages in the curl project. 215 216 ---- start ---- 217 [area]: [short line describing the main effect] 218 -- empty line -- 219 [full description, no wider than 72 columns that describes as much as 220 possible as to why this change is made, and possibly what things 221 it fixes and everything else that is related, 222 -- end -- 223 224 The first line is a succinct description of the change and should ideally work 225 as a single line in the RELEASE NOTES. 226 227 - use the imperative, present tense: **change** not "changed" nor "changes" 228 - do not capitalize the first letter 229 - no period (.) at the end 230 231 The `[area]` in the first line can be `http2`, `cookies`, `openssl` or 232 similar. There is no fixed list to select from but using the same "area" as 233 other related changes could make sense. 234 235 ## Commit message keywords 236 237 Use the following ways to improve the message and provide pointers to related 238 work. 239 240 - `Follow-up to {shorthash}` - if this fixes or continues a previous commit; 241 add a `Ref:` that commit's PR or issue if it is not a small, obvious fix; 242 followed by an empty line 243 244 - `Bug: URL` to the source of the report or more related discussion; use 245 `Fixes` for GitHub issues instead when that is appropriate. 246 247 - `Approved-by: John Doe` - credit someone who approved the PR. 248 249 - `Authored-by: John Doe` - credit the original author of the code; only use 250 this if you cannot use `git commit --author=...`. 251 252 - `Signed-off-by: John Doe` - we do not use this, but do not bother removing 253 it. 254 255 - `whatever-else-by:` credit all helpers, finders, doers; try to use one of 256 the following keywords if at all possible, for consistency: `Acked-by:`, 257 `Assisted-by:`, `Co-authored-by:`, `Found-by:`, `Reported-by:`, 258 `Reviewed-by:`, `Suggested-by:`, `Tested-by:`. 259 260 - `Ref: #1234` - if this is related to a GitHub issue or PR, possibly one that 261 has already been closed. 262 263 - `Ref: URL` to more information about the commit; use `Bug:` instead for a 264 reference to a bug on another bug tracker] 265 266 - `Fixes #1234` - if this fixes a GitHub issue; GitHub closes the issue once 267 this commit is merged. 268 269 - `Closes #1234` - if this merges a GitHub PR; GitHub closes the PR once this 270 commit is merged. 271 272 Do not forget to use commit with `--author` if you commit someone else's work, 273 and make sure that you have your own user and email setup correctly in git 274 before you commit. 275 276 Add whichever header lines as appropriate, with one line per person if more 277 than one person was involved. There is no need to credit yourself unless you 278 are using `--author` which hides your identity. Do not include people's email 279 addresses in headers to avoid spam, unless they are already public from a 280 previous commit; saying `{userid} on github` is OK. 281 282 ## Push Access 283 284 If you are a frequent contributor, you may be given push access to the git 285 repository and then you are able to push your changes straight into the git 286 repository instead of sending changes as pull requests or by mail as patches. 287 288 Just ask if this is what you would want. You are required to have posted 289 several high quality patches first, before you can be granted push access. 290 291 ## Useful resources 292 - [Webinar on getting code into cURL](https://www.youtube.com/watch?v=QmZ3W1d6LQI) 293 294 # Update copyright and license information 295 296 There is a CI job called **REUSE compliance / check** that runs on every pull 297 request and commit to verify that the *REUSE state* of all files are still 298 fine. 299 300 This means that all files need to have their license and copyright information 301 clearly stated. Ideally by having the standard curl source code header, with 302 the `SPDX-License-Identifier` included. If the header does not work, you can 303 use a smaller header or add the information for a specific file to the 304 `REUSE.toml` file. 305 306 You can manually verify the copyright and compliance status by running the 307 [REUSE helper tool](https://github.com/fsfe/reuse-tool): `reuse lint` 308 309 # On AI use in curl 310 311 Guidelines for AI use when contributing to curl. 312 313 ## For security reports and other issues 314 315 If you asked an AI tool to find problems in curl, you **must** make sure to 316 reveal this fact in your report. 317 318 You must also double-check the findings carefully before reporting them to us 319 to validate that the issues are indeed existing and working exactly as the AI 320 says. AI-based tools frequently generate inaccurate or fabricated results. 321 322 Further: it is *rarely* a good idea to just copy and paste an AI generated 323 report to the project. Those generated reports typically are too wordy and 324 rarely to the point (in addition to the common fabricated details). If you 325 actually find a problem with an AI and you have verified it yourself to be 326 true: write the report yourself and explain the problem as you have learned 327 it. This makes sure the AI-generated inaccuracies and invented issues are 328 filtered out early before they waste more people's time. 329 330 As we take security reports seriously, we investigate each report with 331 priority. This work is both time and energy consuming and pulls us away from 332 doing other meaningful work. Fake and otherwise made up security problems 333 effectively prevent us from doing real project work and make us waste time and 334 resources. 335 336 We ban users immediately who submit made up fake reports to the project. 337 338 ## For pull requests 339 340 When contributing content to the curl project, you give us permission to use 341 it as-is and you must make sure you are allowed to distribute it to us. By 342 submitting a change to us, you agree that the changes can and should be 343 adopted by curl and get redistributed under the curl license. Authors should 344 be explicitly aware that the burden is on them to ensure no unlicensed code is 345 submitted to the project. 346 347 This is independent if AI is used or not. 348 349 When contributing a pull request you should of course always make sure that 350 the proposal is good quality and a best effort that follows our guidelines. A 351 basic rule of thumb is that if someone can spot that the contribution was made 352 with the help of AI, you have more work to do. 353 354 We can accept code written with the help of AI into the project, but the code 355 must still follow coding standards, be written clearly, be documented, feature 356 test cases and adhere to all the normal requirements we have. 357 358 ## For translation 359 360 Translation services help users write reports, texts and documentation in 361 non-native languages and we encourage and welcome such contributors and 362 contributions. 363 364 As AI-based translation tools sometimes have a way to make the output sound a 365 little robotic and add an "AI tone" to the text, you may want to consider 366 mentioning that you used such a tool. Failing to do so risks that maintainers 367 wrongly dismiss translated texts as AI slop.