[thirdparty/openssl.git] / CONTRIBUTING.md

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

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

  [gs]: https://www.openssl.org/community/getting-started.html

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

  [gh]: https://github.com/openssl/openssl

To request new features or report bugs, please open an issue on GitHub

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 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] (CLA), giving us permission to use your code.
    If your contribution is too small to require a CLA (e.g. fixing a spelling
    mistake), place the text "`CLA: trivial`" on a line by itself separated by
    an empty line from the rest of the commit message. It is not sufficient to
    only place the text in the GitHub pull request description.

    [CLA]: 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
    ```

 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. Patches should follow our [coding style][] and compile without warnings.
    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 Travis and AppVeyor are required, and they are started automatically
    whenever a PR is created or updated.

    [coding style]: https://www.openssl.org/policies/codingstyle.html

 5. When at all possible, patches should include tests. These can
    either be added to an existing test, or completely new.  Please see
    test/README 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.
    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. For larger or more important user visible changes, as well as
    security fixes, please add a line in [NEWS.md](NEWS.md).
    On exception, it might be worth adding a multi-line entry (such as
    the entry that announces all the types that became opaque with
    OpenSSL 1.1.0).
    This file helps users get a very quick summary of what comes with a
    specific release, to see if an upgrade is worth the effort.
Commit	Line	Data
2876872f	1	HOW TO CONTRIBUTE TO OpenSSL
5f8e6c50	2	============================
eb05f173	3
5f8e6c50	4	Please visit our [Getting Started][gs] page for other ideas about how to contribute.
eb05f173	5
5f8e6c50 DMSP	6	[gs]: https://www.openssl.org/community/getting-started.html
5f8e6c50 DMSP	7
5f8e6c50 DMSP	8	Development is done on GitHub in the [openssl/openssl][gh] repository.
	9
	10	[gh]: https://github.com/openssl/openssl
eb05f173	11
2876872f	12	To request new features or report bugs, please open an issue on GitHub
c5eed277	13
2876872f RS	14	To submit a patch, please open a pull request on GitHub. If you are thinking
	15	of making a large contribution, open an issue for it before starting work,
	16	to get comments from the community. Someone may be already working on
	17	the same thing or there may be reasons why that feature isn't implemented.
f2b9c257	18
2876872f RS	19	To make it easier to review and accept your pull request, please follow these
	20	guidelines:
	21
5f8e6c50 DMSP	22	1. Anything other than a trivial contribution requires a [Contributor
	23	License Agreement][CLA] (CLA), giving us permission to use your code.
	24	If your contribution is too small to require a CLA (e.g. fixing a spelling
	25	mistake), place the text "`CLA: trivial`" on a line by itself separated by
e955edcd P	26	an empty line from the rest of the commit message. It is not sufficient to
	27	only place the text in the GitHub pull request description.
	28
5f8e6c50	29	[CLA]: https://www.openssl.org/policies/cla.html
e955edcd	30
5f8e6c50	31	To amend a missing "`CLA: trivial`" line after submission, do the following:
257e9d03	32
5f8e6c50	33	```
e955edcd P	34	git commit --amend
	35	[add the line, save and quit the editor]
	36	git push -f
5f8e6c50	37	```
257e9d03	38
5f8e6c50	39	2. All source files should start with the following text (with
f2b9c257 RS	40	appropriate comment characters at the start of each line and the
f2b9c257 RS	41	year(s) updated):
257e9d03	42
5f8e6c50	43	```
f2b9c257 RS	44	Copyright 20xx-20yy The OpenSSL Project Authors. All Rights Reserved.
f2b9c257 RS	45
15133316	46	Licensed under the Apache License 2.0 (the "License"). You may not use
f2b9c257 RS	47	this file except in compliance with the License. You can obtain a copy
	48	in the file LICENSE in the source distribution or at
	49	https://www.openssl.org/source/license.html
5f8e6c50	50	```
f2b9c257	51
5f8e6c50	52	3. Patches should be as current as possible; expect to have to rebase
2876872f RS	53	often. We do not accept merge commits, you will have to remove them
2876872f RS	54	(usually by rebasing) before it will be acceptable.
f2b9c257	55
5f8e6c50 DMSP	56	4. Patches should follow our [coding style][] and compile without warnings.
5f8e6c50 DMSP	57	Where gcc or clang is available you should use the
75737d4f	58	--strict-warnings Configure option. OpenSSL compiles on many varied
2876872f RS	59	platforms: try to ensure you only use portable features. Clean builds
	60	via Travis and AppVeyor are required, and they are started automatically
	61	whenever a PR is created or updated.
f2b9c257	62
5f8e6c50 DMSP	63	[coding style]: https://www.openssl.org/policies/codingstyle.html
	64
	65	5. When at all possible, patches should include tests. These can
7954dced RS	66	either be added to an existing test, or completely new. Please see
7954dced RS	67	test/README for information on the test framework.
49c2a00d	68
5f8e6c50	69	6. New features or changed functionality must include
2876872f RS	70	documentation. Please look at the "pod" files in doc/man[1357] for
	71	examples of our style. Run "make doc-nits" to make sure that your
	72	documentation changes are clean.
029c11c2	73
5f8e6c50	74	7. For user visible changes (API changes, behaviour changes, ...),
ee6c7cde NT	75	consider adding a note in [CHANGES.md](CHANGES.md).
	76	This could be a summarising description of the change, and could
	77	explain the grander details.
df443918	78	Have a look through existing entries for inspiration.
7fa8bcfe	79	Please note that this is NOT simply a copy of git-log one-liners.
ee6c7cde	80	Also note that security fixes get an entry in CHANGES.md.
029c11c2 RL	81	This file helps users get more in depth information of what comes
	82	with a specific release without having to sift through the higher
	83	noise ratio in git-log.
	84
5f8e6c50	85	8. For larger or more important user visible changes, as well as
ee6c7cde NT	86	security fixes, please add a line in [NEWS.md](NEWS.md).
	87	On exception, it might be worth adding a multi-line entry (such as
	88	the entry that announces all the types that became opaque with
	89	OpenSSL 1.1.0).
029c11c2 RL	90	This file helps users get a very quick summary of what comes with a
029c11c2 RL	91	specific release, to see if an upgrade is worth the effort.