CONTRIBUTING.md - third_party/openssl - Git at Google

 HOW TO CONTRIBUTE TO OpenSSL
 ============================

 Please visit our [Getting Started] page for other ideas about how to contribute.

   [Getting Started]: <https://openssl-library.org/community/getting-started>

 Development is done on GitHub in the [openssl/openssl] repository.

   [openssl/openssl]: <https://github.com/openssl/openssl>

 To request a new feature, ask a question, or report a bug,
 please open an [issue on GitHub](https://github.com/openssl/openssl/issues).

 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.

 Similarly, if you plan to submit many pull requests, please start with
 a representative sample (no more than 3 or 4) and open an issue
 explaining your process. The OpenSSL project has limited resources,
 especially when it comes to reviewers, so we appreciate advanced
 communication before submitting many pull requests. In addition,
 contributors should personally evaluate potential patches generated by
 automated tools.

 Provide a clear description of the issue or feature being addressed,
 including any relevant implementation details and, for performance
 improvements, benchmark results.

 Pull requests and commits should be self-contained, enabling readers to
 understand what changed and why without needing to reference related
 issues or having prior knowledge.  Commit messages should include all
 relevant details to help future contributors follow the git history,
 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.

 [Committers]: https://openssl-library.org/about/committers/index.html

 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
     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:

     ```
         One-line summary of trivial change

         Optional main body of commit message. It might contain a sentence
         or two explaining the trivial change.

         CLA: trivial
     ```

     It is not sufficient to only place the text "`CLA: trivial`" in the GitHub
     pull request description.

     [Contributor License Agreement]: <https://www.openssl.org/policies/cla.html>

     To amend a missing "`CLA: trivial`" line after submission, do the following:

     ```
         git commit --amend
         # add the line, save and quit the editor
         git push -f [<repository> [<branch>]]
     ```

  2. All source files should start with the following text (with
     appropriate comment characters at the start of each line and the
     year(s) updated):

     ```
         Copyright 20xx-20yy The OpenSSL Project Authors. All Rights Reserved.

         Licensed under the Apache License 2.0 (the "License").  You may not use
         this file except in compliance with the License.  You can obtain a copy
         in the file LICENSE in the source distribution or at
         https://www.openssl.org/source/license.html
     ```

  3. Patches should be as current as possible; expect to have to rebase
     often. We do not accept merge commits, you will have to remove them
     (usually by rebasing) before it will be acceptable.

  4. Code provided should follow our [coding style] and [documentation policy]
     and compile without warnings.
     Consistent formatting is enforced by using `clang-format` with configuration
     stored in [.clang-format](.clang-format). OpenSSL uses `WebKit` style.
     You can configure git pre-commit to automatically reformat your code with
     [.pre-commit-config.yaml](.pre-commit-config.yaml) configuration.
     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.

     [coding style]: https://openssl-library.org/policies/technical/coding-style/
     [documentation policy]: https://openssl-library.org/policies/technical/documentation-policy/

  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 changes are clean.

  7. For user visible changes (API changes, behaviour changes, ...),
     consider adding a note in [CHANGES.md](CHANGES.md).
     This could be a summarising description of the change, and could
     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).
     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.

  8. Guidelines on how to integrate error output of new crypto library modules
     can be found in [crypto/err/README.md](crypto/err/README.md).

  9. Once your Pull Request gets to the stage of being reviewed fixup commits
     should be used where possible. Fixup commits are squashed when the PR is
     finally merged. Fixup commits are done in the following way:

     ```

         # Add one or more updated files that needed changes
         git add <filename>

         # Do a fixup commit
         # <commit-id> is the id of a previous commit that you want to fix up.
         git commit --fixup <commit-id>

         # Do a non forced push
         git push
     ```

     To view commit-id's use:

     ```
        git log
     ```

 10. If a Pull Request addresses an [issue](https://github.com/openssl/openssl/issues/)
     the commit should include the line:

     ```
         Fixes #XXXXX
     ```

     where XXXXX is the issue number.
	HOW TO CONTRIBUTE TO OpenSSL
	============================

	Please visit our [Getting Started] page for other ideas about how to contribute.

	[Getting Started]: <https://openssl-library.org/community/getting-started>

	Development is done on GitHub in the [openssl/openssl] repository.

	[openssl/openssl]: <https://github.com/openssl/openssl>

	To request a new feature, ask a question, or report a bug,
	please open an [issue on GitHub](https://github.com/openssl/openssl/issues).

	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.

	Similarly, if you plan to submit many pull requests, please start with
	a representative sample (no more than 3 or 4) and open an issue
	explaining your process. The OpenSSL project has limited resources,
	especially when it comes to reviewers, so we appreciate advanced
	communication before submitting many pull requests. In addition,
	contributors should personally evaluate potential patches generated by
	automated tools.

	Provide a clear description of the issue or feature being addressed,
	including any relevant implementation details and, for performance
	improvements, benchmark results.

	Pull requests and commits should be self-contained, enabling readers to
	understand what changed and why without needing to reference related
	issues or having prior knowledge. Commit messages should include all
	relevant details to help future contributors follow the git history,
	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.

	[Committers]: https://openssl-library.org/about/committers/index.html

	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
	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:

	```
	One-line summary of trivial change

	Optional main body of commit message. It might contain a sentence
	or two explaining the trivial change.

	CLA: trivial
	```

	It is not sufficient to only place the text "`CLA: trivial`" in the GitHub
	pull request description.

	[Contributor License Agreement]: <https://www.openssl.org/policies/cla.html>

	To amend a missing "`CLA: trivial`" line after submission, do the following:

	```
	git commit --amend
	# add the line, save and quit the editor
	git push -f [<repository> [<branch>]]
	```

	2. All source files should start with the following text (with
	appropriate comment characters at the start of each line and the
	year(s) updated):

	```
	Copyright 20xx-20yy The OpenSSL Project Authors. All Rights Reserved.

	Licensed under the Apache License 2.0 (the "License"). You may not use
	this file except in compliance with the License. You can obtain a copy
	in the file LICENSE in the source distribution or at
	https://www.openssl.org/source/license.html
	```

	3. Patches should be as current as possible; expect to have to rebase
	often. We do not accept merge commits, you will have to remove them
	(usually by rebasing) before it will be acceptable.

	4. Code provided should follow our [coding style] and [documentation policy]
	and compile without warnings.
	Consistent formatting is enforced by using `clang-format` with configuration
	stored in [.clang-format](.clang-format). OpenSSL uses `WebKit` style.
	You can configure git pre-commit to automatically reformat your code with
	[.pre-commit-config.yaml](.pre-commit-config.yaml) configuration.
	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.

	[coding style]: https://openssl-library.org/policies/technical/coding-style/
	[documentation policy]: https://openssl-library.org/policies/technical/documentation-policy/

	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 changes are clean.

	7. For user visible changes (API changes, behaviour changes, ...),
	consider adding a note in [CHANGES.md](CHANGES.md).
	This could be a summarising description of the change, and could
	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).
	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.

	8. Guidelines on how to integrate error output of new crypto library modules
	can be found in [crypto/err/README.md](crypto/err/README.md).

	9. Once your Pull Request gets to the stage of being reviewed fixup commits
	should be used where possible. Fixup commits are squashed when the PR is
	finally merged. Fixup commits are done in the following way:

	```

	# Add one or more updated files that needed changes
	git add <filename>

	# Do a fixup commit
	# <commit-id> is the id of a previous commit that you want to fix up.
	git commit --fixup <commit-id>

	# Do a non forced push
	git push
	```

	To view commit-id's use:

	```
	git log
	```

	10. If a Pull Request addresses an [issue](https://github.com/openssl/openssl/issues/)
	the commit should include the line:

	```
	Fixes #XXXXX
	```

	where XXXXX is the issue number.