Commit 37d35a863a for openssl.org
commit 37d35a863ab1187fc6f46745bd4fa70752a67e1c
Author: Richard Levitte <levitte@openssl.foundation>
Date: Wed Sep 9 10:52:06 2026 +0200
CONTRIBUTING.md: restructure, fix inaccuracies and omissions
The document had a single heading for its whole length, and the
bulk-submission guidance buried its actual rule ("no more than three
or four open pull requests at a time") in the third paragraph of a
five-paragraph passage, after the rationale. Contributors scanning
for the rules were likely to miss both. Give the document section
headings, split the preamble into titled subsections, and rewrite
the bulk-submission passage to lead with the rule, followed by the
rationale and the consequence.
Content fixes, found while verifying the document against current
practice:
- The only route given for reporting a bug was to open a public
GitHub issue, and the document never mentioned how to report a
security vulnerability; a contributor following it would disclose
security issues publicly, contrary to the security policy. Add a
short section directing security reports to
openssl-security@openssl.org.
- The approval flow description stated that the
'approval: ready to merge' label appears 24 hours after
'approval: done'. In practice the transition is deferred by any
activity on the PR in the meantime, which is a recurring source of
contributor confusion; say so.
- Say which branch pull requests should target, and that
cherry-picking to release branches is handled at merge time.
- Replace the doubled CLA version criteria ("v1.1 or later" and
"signed after June 2026") with a single durable formulation.
- Merge the doubled --strict-warnings requirement in guideline 5.
- Note that first-time contributors may need a maintainer to
approve CI workflow runs.
- Drop a redundant CHANGES.md link, fix "PR's", "commit-id's",
and "in github", and remove a stray blank line inside a code
fence.
Assisted-by: Pi:moonshotai/kimi-k3
Signed-off-by: Richard Levitte <levitte@openssl.foundation>
Reviewed-by: Matt Caswell <matt@openssl.foundation>
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Merge-date: Wed Nov 4 16:47:38 2026
Merged-from: https://github.com/openssl/openssl/pull/32759
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e4ade85d9b..671866ab1b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,47 +12,70 @@ Development is done on GitHub in the [openssl/openssl] repository.
To request a new feature, ask a question, or report a bug,
please open an [issue on GitHub](https://github.com/openssl/openssl/issues).
+Reporting security issues
+-------------------------
+
+If you believe you have found a security vulnerability, please do NOT
+open a public GitHub issue or pull request for it. Report it privately
+to openssl-security@openssl.org instead; see our [security policy] for
+details.
+
+ [security policy]: <https://openssl-library.org/policies/general/security-policy/>
+
+Submitting pull requests
+------------------------
+
To submit a patch or implement a new feature, please open a
[pull request on GitHub](https://github.com/openssl/openssl/pulls).
+Pull requests normally target the `master` branch; the release branches
+(`openssl-3.x`) take bug fixes and documentation only, and changes that
+apply to them are cherry-picked by the committers at merge time.
+
If you are thinking of making a large contribution,
open an issue for it before starting work, to get comments from the community.
Someone may be already working on the same thing,
or there may be special reasons why a feature is not implemented.
-Do not submit changes in bulk. Review, not authorship, is the scarce
-resource in this project: every pull request consumes the attention of
-at least two committers, and a batch of them submitted together does not get
-reviewed any faster than the same batch submitted over months. It
-merely displaces the review of everyone else's work, including security
-fixes.
+### How many pull requests at a time
+
+Keep to no more than three or four open pull requests at a time, and let
+those be reviewed to completion before opening more. Review, not
+authorship, is the scarce resource in this project: every pull request
+consumes the attention of at least two committers, and a batch submitted
+together does not get reviewed any faster than the same batch submitted
+over months. It merely displaces the review of everyone else's work,
+including security fixes. This applies regardless of how good the
+individual changes are, and it is not satisfied by spacing submissions
+out over a few hours or days. Pull requests opened well in excess of
+this may be closed without review, with a request to resubmit at a
+sustainable rate.
+
+If you are working through a list of candidate changes, choose those
+three or four deliberately: send us the ones you consider most
+important, rather than the first on the list or the quickest to write,
+and explain in each why it matters. You know your list; we do not, and
+without that ranking the judgement of what to look at first falls on the
+reviewers.
Nor is the answer to bundle them together. A pull request carrying
twenty unrelated fixes is harder to review than any one of them alone,
-cannot be merged a piece at a time, and leaves every change in it blocked
-behind the one a reviewer disagrees with. Each pull request should address
-one logical change (perhaps spread across multiple commits); what has to give
-is how many you submit, not how much you put in each one.
+cannot be merged a piece at a time, and leaves every change in it
+blocked behind the one a reviewer disagrees with. Each pull request
+should address one logical change (perhaps spread across multiple
+commits); what has to give is how many you submit, not how much you put
+in each one.
-Keep to no more than three or four open pull requests at a time, and let
-those be reviewed to completion before opening more. If you are working
-through a list of candidate changes, then choose those three or four
-deliberately: send us the ones you consider most important, rather than the
-first on the list or the quickest to write, and explain in each why it
-matters. You know your list; we do not, and without that ranking the
-judgement of what to look at first falls on the reviewers. Pull requests
-opened well in excess of this may be closed without review, with a request to
-resubmit at a sustainable rate.
-
-This applies regardless of how good the individual changes are, and it
-is not satisfied by spacing submissions out over a few hours or days.
+### You are the author of what you submit
You are the author of everything you submit, whatever produced the first
draft of it. Before opening a pull request you must have read the
change in full, understood why it is correct, built and tested it
yourself, and satisfied yourself that the problem it fixes is real. You
-must be prepared to answer a reviewer's questions about any line of it. The
-`Assisted-by:` trailer (see below) discloses that a tool was used; it does not
-transfer responsibility for the result.
+must be prepared to answer a reviewer's questions about any line of it.
+The `Assisted-by:` trailer (see below) discloses that a tool was used;
+it does not transfer responsibility for the result.
+
+### Descriptions and commit messages
Provide a clear description of the issue or feature being addressed,
including any relevant implementation details and, for performance
@@ -66,16 +89,24 @@ with clear explanations of what is changing and why. Long descriptions
are encouraged if they aid understanding. Commit message titles (their
first line) should be kept to 50-70 characters if possible.
-Pull Requests (PR's) go through multiple phases before they are merged. In the
-first phase the label 'approval: review pending' is added. Once you receive 2 or
-more approvals from [Committers] the label is changed to 'approval: done' and
-24 hours after this the label changes to 'approval: ready to merge'. At some time
-after this your PR will be merged and the PR is closed. Reviewers may ask you to
-make changes at any phase before the Pull Request is merged, and any changes
-(that are not just a rebase) will require re-approval.
+### The review process
+
+Pull requests (PRs) go through multiple phases before they are merged.
+In the first phase the label 'approval: review pending' is added. Once
+you receive two or more approvals from [Committers] the label is changed
+to 'approval: done', and 24 hours after this the label changes to
+'approval: ready to merge', provided the PR has not been updated in the
+meantime (any push, comment, or label change defers the transition,
+which is then done manually by a committer). At some time after this
+your PR will be merged and the PR is closed. Reviewers may ask you to
+make changes at any phase before the pull request is merged, and any
+changes (that are not just a rebase) will require re-approval.
[Committers]: https://openssl-library.org/about/committers/index.html
+Pull request guidelines
+-----------------------
+
To make it easier to review and accept your pull request, please follow these
guidelines:
@@ -126,9 +157,9 @@ guidelines:
Assisted-by: GitHub Copilot:gpt-4.1
```
- You will need to have signed a v1.1 or later CLA in order to
- include AI-generated content in your contribution. CLAs signed
- after June 2026 will have the requisite clauses.
+ You will need to have signed a CLA that includes the AI clauses
+ (CLA v1.1 or later) in order to include AI-generated content in
+ your contribution.
Consult the [OpenSSL AI Code and Documentation Contribution
Policy] if an AI model assisted with the creation of your
@@ -155,8 +186,10 @@ guidelines:
(usually by rebasing) before it will be acceptable.
5. Code provided should follow our [coding style](STYLE.md) and
- [documentation policy](DOCUMENTATION.md) and compile without warnings when
- using a --strict-warnings configuration.
+ [documentation policy](DOCUMENTATION.md) and compile without warnings.
+ Where `gcc` or `clang` is available, use the `--strict-warnings`
+ `Configure` option to verify this. OpenSSL compiles on many varied
+ platforms: try to ensure you only use portable features.
Consistent formatting is enforced by using `clang-format` with configuration
stored in [.clang-format](.clang-format). OpenSSL uses `WebKit` style.
@@ -165,11 +198,9 @@ guidelines:
There is also a [Perl tool](util/reformat-patches.sh) to help with
reformatting existing patches.
- Where `gcc` or `clang` is available, you should use the
- `--strict-warnings` `Configure` option. OpenSSL compiles on many varied
- platforms: try to ensure you only use portable features.
Clean builds via GitHub Actions are required. They are started automatically
- whenever a PR is created or updated by committers.
+ whenever a PR is created or updated (for first-time contributors, a
+ maintainer may need to approve the workflow runs).
6. When at all possible, code contributions should include tests. These can
either be added to an existing test, or completely new. Please see
@@ -186,7 +217,7 @@ guidelines:
explain the grander details.
Have a look through existing entries for inspiration.
Please note that this is NOT simply a copy of git-log one-liners.
- Also note that security fixes get an entry in [CHANGES.md](CHANGES.md).
+ Also note that security fixes get an entry in CHANGES.md.
This file helps users get more in-depth information of what comes
with a specific release without having to sift through the higher
noise ratio in git-log.
@@ -199,7 +230,6 @@ guidelines:
finally merged. Fixup commits are done in the following way:
```
-
# Add one or more updated files that needed changes
git add <filename>
@@ -211,7 +241,7 @@ guidelines:
git push
```
- To view commit-id's use:
+ To view commit-ids use:
```
git log
@@ -224,4 +254,4 @@ guidelines:
Fixes: LINK
```
- where LINK is the https link to the issue in github.
+ where LINK is the https link to the issue in GitHub.