From e2dbf16d0f0e66282cdffa10c2ee54f45b908d87 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Sat, 2 Dec 2023 15:54:27 +0100 Subject: [PATCH] CONTRIBUTING.md: add reference to util/check-format.pl and fix several nits --- CONTRIBUTING.md | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11c31e0d696bd..0528df95ba583 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,19 +9,22 @@ Development is done on GitHub in the [openssl/openssl] repository. [openssl/openssl]: -To request new features or report bugs, please open an issue on GitHub +To request new a feature, ask a question, or report a bug, +please open an [issue on GitHub](https://github.com/openssl/openssl/issues). -To submit a patch, please open a pull request on GitHub. 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 reasons why that feature isn't implemented. +To submit a patch or implement a new feature, please open a +[pull request on GitHub](https://github.com/openssl/openssl/pulls). +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. To make it easier to review and accept your pull request, please follow these guidelines: 1. Anything other than a trivial contribution requires a [Contributor License Agreement] (CLA), giving us permission to use your code. - If your contribution is too small to require a CLA (e.g. fixing a spelling + If your contribution is too small to require a CLA (e.g., fixing a spelling mistake), then place the text "`CLA: trivial`" on a line by itself below the rest of your commit message separated by an empty line, like this: @@ -64,22 +67,24 @@ guidelines: often. We do not accept merge commits, you will have to remove them (usually by rebasing) before it will be acceptable. - 4. Patches should follow our [coding style] and compile without warnings. + 4. Code provided should follow our [coding style] and compile without warnings. + There is a [Perl tool](util/check-format.pl) that helps + finding code formatting mistakes and other coding style nits. 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 and AppVeyor are required, and they are started automatically - whenever a PR is created or updated. + GitHub Actions and AppVeyor are required. They are started automatically + whenever a PR is created or updated by committers. [coding style]: https://www.openssl.org/policies/technical/coding-style.html - 5. When at all possible, patches should include tests. These can + 5. When at all possible, code contributions should include tests. These can either be added to an existing test, or completely new. Please see [test/README.md](test/README.md) for information on the test framework. 6. New features or changed functionality must include - documentation. Please look at the "pod" files in doc/man[1357] for - examples of our style. Run "make doc-nits" to make sure that your + documentation. Please look at the `.pod` files in `doc/man[1357]` for + examples of our style. Run `make doc-nits` to make sure that your documentation changes are clean. 7. For user visible changes (API changes, behaviour changes, ...), @@ -89,7 +94,7 @@ guidelines: 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). - This file helps users get more in depth information of what comes + 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.