1HOW TO CONTRIBUTE TO OpenSSL 2============================ 3 4Please visit our [Getting Started] page for other ideas about how to contribute. 5 6 [Getting Started]: <https://openssl-library.org/community/getting-started> 7 8Development is done on GitHub in the [openssl/openssl] repository. 9 10 [openssl/openssl]: <https://github.com/openssl/openssl> 11 12To request a new feature, ask a question, or report a bug, 13please open an [issue on GitHub](https://github.com/openssl/openssl/issues). 14 15To submit a patch or implement a new feature, please open a 16[pull request on GitHub](https://github.com/openssl/openssl/pulls). 17If you are thinking of making a large contribution, 18open an issue for it before starting work, to get comments from the community. 19Someone may be already working on the same thing, 20or there may be special reasons why a feature is not implemented. 21 22Similarly, if you plan to submit many pull requests, please start with 23a representative sample (no more than 3 or 4) and open an issue 24explaining your process. The OpenSSL project has limited resources, 25especially when it comes to reviewers, so we appreciate advanced 26communication before submitting many pull requests. In addition, 27contributors should personally evaluate potential patches generated by 28automated tools. 29 30Provide a clear description of the issue or feature being addressed, 31including any relevant implementation details and, for performance 32improvements, benchmark results. 33 34Pull requests and commits should be self-contained, enabling readers to 35understand what changed and why without needing to reference related 36issues or having prior knowledge. Commit messages should include all 37relevant details to help future contributors follow the git history, 38with clear explanations of what is changing and why. Long descriptions 39are encouraged if they aid understanding. Commit message titles (their 40first line) should be kept to 50-70 characters if possible. 41 42To make it easier to review and accept your pull request, please follow these 43guidelines: 44 45 1. Anything other than a trivial contribution requires a [Contributor 46 License Agreement] (CLA), giving us permission to use your code. 47 If your contribution is too small to require a CLA (e.g., fixing a spelling 48 mistake), then place the text "`CLA: trivial`" on a line by itself below 49 the rest of your commit message separated by an empty line, like this: 50 51 ``` 52 One-line summary of trivial change 53 54 Optional main body of commit message. It might contain a sentence 55 or two explaining the trivial change. 56 57 CLA: trivial 58 ``` 59 60 It is not sufficient to only place the text "`CLA: trivial`" in the GitHub 61 pull request description. 62 63 [Contributor License Agreement]: <https://www.openssl.org/policies/cla.html> 64 65 To amend a missing "`CLA: trivial`" line after submission, do the following: 66 67 ``` 68 git commit --amend 69 # add the line, save and quit the editor 70 git push -f [<repository> [<branch>]] 71 ``` 72 73 2. Similarly, if a non-trivial portion of a contribution was created 74 using an AI tool, you must declare which agent and model were used. 75 This is done by adding `Assisted-by: {agent}:{model}` below the commit 76 message: 77 78 ``` 79 One-line summary of change with AI-generated portions 80 81 Assisted-by: Claude:claude-sonnet-4-6 82 ``` 83 84 Multiple Assisted-by trailers can be included if multiple tools were used: 85 86 ``` 87 Assisted-by: Claude:claude-sonnet-4-6 88 Assisted-by: ChatGPT:gpt-4o 89 Assisted-by: GitHub Copilot:gpt-4.1 90 ``` 91 92 You will need to have signed a v1.1 or later CLA in order to 93 include AI-generated content in your contribution. CLAs signed 94 after June 2026 will have the requisite clauses. 95 96 Consult the [OpenSSL AI Code and Documentation Contribution 97 Policy] if an AI model assisted with the creation of your 98 contribution. 99 100 [OpenSSL AI Code and Documentation Contribution 101 Policy]: <https://openssl-library.org/policies/general/ai-policy/> 102 103 3. All source files should start with the following text (with 104 appropriate comment characters at the start of each line and the 105 year(s) updated): 106 107 ``` 108 Copyright 20xx-20yy The OpenSSL Project Authors. All Rights Reserved. 109 110 Licensed under the Apache License 2.0 (the "License"). You may not use 111 this file except in compliance with the License. You can obtain a copy 112 in the file LICENSE in the source distribution or at 113 https://www.openssl.org/source/license.html 114 ``` 115 116 4. Patches should be as current as possible; expect to have to rebase 117 often. We do not accept merge commits, you will have to remove them 118 (usually by rebasing) before it will be acceptable. 119 120 5. Code provided should follow our [coding style] and [documentation policy] 121 and compile without warnings. 122 There is a [Perl tool](util/check-format.pl) that helps 123 finding code formatting mistakes and other coding style nits. 124 Where `gcc` or `clang` is available, you should use the 125 `--strict-warnings` `Configure` option. OpenSSL compiles on many varied 126 platforms: try to ensure you only use portable features. 127 Clean builds via GitHub Actions are required. They are started automatically 128 whenever a PR is created or updated by committers. 129 130 [coding style]: https://openssl-library.org/policies/technical/coding-style/ 131 [documentation policy]: https://openssl-library.org/policies/technical/documentation-policy/ 132 133 6. When at all possible, code contributions should include tests. These can 134 either be added to an existing test, or completely new. Please see 135 [test/README.md](test/README.md) for information on the test framework. 136 137 7. New features or changed functionality must include 138 documentation. Please look at the `.pod` files in `doc/man[1357]` for 139 examples of our style. Run `make doc-nits` to make sure that your 140 documentation changes are clean. 141 142 8. For user visible changes (API changes, behaviour changes, ...), 143 consider adding a note in [CHANGES.md](CHANGES.md). 144 This could be a summarising description of the change, and could 145 explain the grander details. 146 Have a look through existing entries for inspiration. 147 Please note that this is NOT simply a copy of git-log one-liners. 148 Also note that security fixes get an entry in [CHANGES.md](CHANGES.md). 149 This file helps users get more in-depth information of what comes 150 with a specific release without having to sift through the higher 151 noise ratio in git-log. 152 153 9. Guidelines on how to integrate error output of new crypto library modules 154 can be found in [crypto/err/README.md](crypto/err/README.md). 155