We also hang out on IRC in #curl on libera.chat
If you are at all interested in the code side of things, consider clicking
-'watch' on the [curl repo on GitHub](https://github.com/curl/curl) to be
+'watch' on the [curl repository on GitHub](https://github.com/curl/curl) to be
notified of pull requests and new issues posted there.
## License and copyright
### Write Separate Changes
-It is annoying when you get a huge patch from someone that is said to fix 511
-odd problems, but discussions and opinions do not agree with 510 of them - or
-509 of them were already fixed in a different way. Then the person merging
-this change needs to extract the single interesting patch from somewhere
-within the huge pile of source, and that creates a lot of extra work.
+It is annoying when you get a huge patch from someone that is said to fix 11
+odd problems, but discussions and opinions do not agree with 10 of them - or 9
+of them were already fixed in a different way. Then the person merging this
+change needs to extract the single interesting patch from somewhere within the
+huge pile of source, and that creates a lot of extra work.
Preferably, each fix that corrects a problem should be in its own patch/commit
with its own description/commit message stating exactly what they correct so
to write tests for, do explain exactly how you have otherwise tested and
verified your changes.
-## Submit Your Changes
+# Submit Your Changes
-### How to get your changes into the main sources
+## Get your changes merged
Ideally you file a [pull request on
GitHub](https://github.com/curl/curl/pulls), but you can also send your plain
are not anxious to get your patch accepted and we tend to simply drop such
changes.
-### About pull requests
+## About pull requests
With GitHub it is easy to send a [pull
request](https://github.com/curl/curl/pulls) to the curl project to have
user support. More signs that people want this to happen. It could be in the
form of messages saying so, or thumbs-up reactions on GitHub.
-### Making quality changes
+## When the pull request is approved
+
+If it does not seem to get approved when you think it is ready - feel free to
+ask for approval.
+
+Once your pull request has been approved it can be merged by a maintainer.
+
+For new features, or changes, we require that the *feature window* is open for
+the pull request to be merged. This is typically a three week period that
+starts ten days after a previous release. New features submitted as pull
+requests while the window is closed simply have to wait until it opens to get
+merged.
+
+If time passes without your approved pull request gets merged: feel free to
+ask what more you can do to make it happen.
+
+## Making quality changes
Make the patch against as recent source versions as possible.
been incorporated or responded to after some weeks, consider resubmitting it
to the list or better yet: change it to a pull request.
-### Commit messages
+## Commit messages
-A short guide to how to write git commit messages in the curl project.
+How to write git commit messages in the curl project.
---- start ----
[area]: [short line describing the main effect]
-- empty line --
[full description, no wider than 72 columns that describes as much as
possible as to why this change is made, and possibly what things
- it fixes and everything else that is related, with unwieldy URLs replaced
- with references like [0], [1], etc.]
- -- empty line --
- [[0] URL - Reference to a URL in the description, almost like Markdown;
- the last numbered reference is followed by an -- empty line -- ]
- [Follow-up to {shorthash} - if this fixes or continues a previous commit;
- add a Ref: that commit's PR or issue if it's not a small, obvious fix;
- followed by an -- empty line -- ]
- [Bug: URL to the source of the report or more related discussion; use Fixes
- for GitHub issues instead when that is appropriate]
- [Approved-by: John Doe - credit someone who approved the PR; if you are
- committing this for someone else using --author=... you do not need this
- as you are implicitly approving it by committing]
- [Authored-by: John Doe - credit the original author of the code; only use
- this if you cannot use "git commit --author=..."]
- [Signed-off-by: John Doe - we do not use this, but do not bother removing it]
- [whatever-else-by: credit all helpers, finders, doers; try to use one of
- the following keywords if at all possible, for consistency:
- Acked-by:, Assisted-by:, Co-authored-by:, Found-by:, Reported-by:,
- Reviewed-by:, Suggested-by:, Tested-by:]
- [Ref: #1234 - if this is related to a GitHub issue or PR, possibly one that
- has already been closed]
- [Ref: URL to more information about the commit; use Bug: instead for
- a reference to a bug on another bug tracker]
- [Fixes #1234 - if this closes a GitHub issue; GitHub closes the issue once
- this commit is merged]
- [Closes #1234 - if this closes a GitHub PR; GitHub closes the PR once this
- commit is merged]
- ---- stop ----
-
-The first line is a succinct description of the change:
-
- - use the imperative, present tense: "change" not "changed" nor "changes"
+ it fixes and everything else that is related,
+ -- end --
+
+The first line is a succinct description of the change and should ideally work
+as a single line in the RELEASE NOTES.
+
+ - use the imperative, present tense: **change** not "changed" nor "changes"
- do not capitalize the first letter
- no period (.) at the end
similar. There is no fixed list to select from but using the same "area" as
other related changes could make sense.
-Do not forget to use commit --author=... if you commit someone else's work, and
-make sure that you have your own user and email setup correctly in git before
-you commit.
+## Commit message keywords
-Add whichever header lines as appropriate, with one line per person if more
-than one person was involved. There is no need to credit yourself unless you
-are using --author=... which hides your identity. Do not include people's
-email addresses in headers to avoid spam, unless they are already public from
-a previous commit; saying `{userid} on github` is OK.
+Use the following ways to improve the message and provide pointers to related
+work.
-### Write Access to git Repository
+- `Follow-up to {shorthash}` - if this fixes or continues a previous commit;
+add a `Ref:` that commit's PR or issue if it is not a small, obvious fix;
+followed by an empty line
-If you are a frequent contributor, you may be given push access to the git
-repository and then you are able to push your changes straight into the git
-repo instead of sending changes as pull requests or by mail as patches.
+- `Bug: URL` to the source of the report or more related discussion; use
+`Fixes` for GitHub issues instead when that is appropriate.
-Just ask if this is what you would want. You are required to have posted
-several high quality patches first, before you can be granted push access.
-
-### How To Make a Patch with git
-
-You need to first checkout the repository:
-
- git clone https://github.com/curl/curl.git
-
-You then proceed and edit all the files you like and you commit them to your
-local repository:
-
- git commit [file]
+- `Approved-by: John Doe` - credit someone who approved the PR.
-As usual, group your commits so that you commit all changes at once that
-constitute a logical change.
+- `Authored-by: John Doe` - credit the original author of the code; only use
+this if you cannot use `git commit --author=...`.
-Once you have done all your commits and you are happy with what you see, you
-can make patches out of your changes that are suitable for mailing:
+- `Signed-off-by: John Doe` - we do not use this, but do not bother removing
+ it.
- git format-patch remotes/origin/master
+- `whatever-else-by:` credit all helpers, finders, doers; try to use one of
+the following keywords if at all possible, for consistency: `Acked-by:`,
+`Assisted-by:`, `Co-authored-by:`, `Found-by:`, `Reported-by:`,
+`Reviewed-by:`, `Suggested-by:`, `Tested-by:`.
-This creates files in your local directory named `NNNN-[name].patch` for each
-commit.
+- `Ref: #1234` - if this is related to a GitHub issue or PR, possibly one that
+has already been closed.
-Now send those patches off to the curl-library list. You can of course opt to
-do that with the 'git send-email' command.
+- `Ref: URL` to more information about the commit; use `Bug:` instead for a
+reference to a bug on another bug tracker]
-### How To Make a Patch without git
+- `Fixes #1234` - if this fixes a GitHub issue; GitHub closes the issue once
+this commit is merged.
-Keep a copy of the unmodified curl sources. Make your changes in a separate
-source tree. When you think you have something that you want to offer the
-curl community, use GNU diff to generate patches.
+- `Closes #1234` - if this merges a GitHub PR; GitHub closes the PR once this
+commit is merged.
-If you have modified a single file, try something like:
+Do not forget to use commit with `--author` if you commit someone else's work,
+and make sure that you have your own user and email setup correctly in git
+before you commit.
- diff -u unmodified-file.c my-changed-one.c > my-fixes.diff
+Add whichever header lines as appropriate, with one line per person if more
+than one person was involved. There is no need to credit yourself unless you
+are using `--author` which hides your identity. Do not include people's email
+addresses in headers to avoid spam, unless they are already public from a
+previous commit; saying `{userid} on github` is OK.
-If you have modified several files, possibly in different directories, you
-can use diff recursively:
+## Push Access
- diff -ur curl-original-dir curl-modified-sources-dir > my-fixes.diff
+If you are a frequent contributor, you may be given push access to the git
+repository and then you are able to push your changes straight into the git
+repository instead of sending changes as pull requests or by mail as patches.
-The GNU diff and GNU patch tools exist for virtually all platforms, including
-all kinds of Unixes and Windows.
+Just ask if this is what you would want. You are required to have posted
+several high quality patches first, before you can be granted push access.
-### Useful resources
+## Useful resources
- [Webinar on getting code into cURL](https://www.youtube.com/watch?v=QmZ3W1d6LQI)
-## Update copyright and license information
+# Update copyright and license information
There is a CI job called **REUSE compliance / check** that runs on every pull
request and commit to verify that the *REUSE state* of all files are still
This means that all files need to have their license and copyright information
clearly stated. Ideally by having the standard curl source code header, with
-the SPDX-License-Identifier included. If the header does not work, you can use a
-smaller header or add the information for a specific file to the `REUSE.toml`
-file.
+the `SPDX-License-Identifier` included. If the header does not work, you can
+use a smaller header or add the information for a specific file to the
+`REUSE.toml` file.
You can manually verify the copyright and compliance status by running the
[REUSE helper tool](https://github.com/fsfe/reuse-tool): `reuse lint`
projects / thirdparty / curl.git / commitdiff
