|
| 1 | +<!-- |
| 2 | +Copyright (c) 2017, 2017 IBM Corp. and others |
| 3 | +
|
| 4 | +This program and the accompanying materials are made available under |
| 5 | +the terms of the Eclipse Public License 2.0 which accompanies this |
| 6 | +distribution and is available at https://www.eclipse.org/legal/epl-2.0/ |
| 7 | +or the Apache License, Version 2.0 which accompanies this distribution and |
| 8 | +is available at https://www.apache.org/licenses/LICENSE-2.0. |
| 9 | +
|
| 10 | +This Source Code may also be made available under the following |
| 11 | +Secondary Licenses when the conditions for such availability set |
| 12 | +forth in the Eclipse Public License, v. 2.0 are satisfied: GNU |
| 13 | +General Public License, version 2 with the GNU Classpath |
| 14 | +Exception [1] and GNU General Public License, version 2 with the |
| 15 | +OpenJDK Assembly Exception [2]. |
| 16 | +
|
| 17 | +[1] https://www.gnu.org/software/classpath/license.html |
| 18 | +[2] http://openjdk.java.net/legal/assembly-exception.html |
| 19 | +
|
| 20 | +SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 |
| 21 | +--> |
| 22 | + |
| 23 | +# Contributing to Eclipse OpenJ9 |
| 24 | + |
| 25 | +Thank you for your interest in Eclipse OpenJ9! |
| 26 | + |
| 27 | +We welcome and encourage all kinds of contributions to the project, not only |
| 28 | +code. This includes bug reports, user experience feedback, assistance in |
| 29 | +reproducing issues and more. Contributions to the website |
| 30 | +(https://github.com/eclipse/openj9-website), to the system verification tests |
| 31 | +(https://github.com/eclipse/openj9-systemtest), or Eclipse OMR |
| 32 | +(https://github.com/eclipse/omr) which is an integral part of OpenJ9 are all |
| 33 | +also welcome. |
| 34 | + |
| 35 | + |
| 36 | +## Submitting a contribution to OpenJ9 |
| 37 | + |
| 38 | +You can propose contributions by sending pull requests (PRs) through GitHub. |
| 39 | +Following these guidelines will help us merge your pull requests smoothly: |
| 40 | + |
| 41 | +1. Your pull request is an opportunity to explain both what changes you'd like |
| 42 | + pulled in, but also _why_ you'd like them added. Providing clarity on why |
| 43 | + you want changes makes it easier to accept, and provides valuable context to |
| 44 | + review. |
| 45 | + |
| 46 | +2. Follow the commit guidelines found below. |
| 47 | + |
| 48 | +3. We encourage you to open a pull request early, and mark it as "Work In |
| 49 | + Progress", by prefixing the PR title with "WIP". This allows feedback to |
| 50 | + start early, and helps create a better end product. Committers will wait |
| 51 | + until after you've removed the WIP prefix to merge your changes. |
| 52 | + |
| 53 | +4. Please carefully read and adhere to the legal considerations and |
| 54 | + copyright/license requirements outlined below. |
| 55 | + |
| 56 | +## Commit Guidelines |
| 57 | + |
| 58 | +The first line describes the change made. It is written in the imperative mood, |
| 59 | +and should say what happens when the patch is applied. Keep it short and |
| 60 | +simple. The first line should be less than 70 characters, where reasonable, |
| 61 | +and should be written in sentence case preferably not ending in a period. |
| 62 | +Leave a blank line between the first line and the message body. |
| 63 | + |
| 64 | +The body should be wrapped at 72 characters, where reasonable. |
| 65 | + |
| 66 | +Include as much information in your commit as possible. You may want to include |
| 67 | +designs and rationale, examples and code, or issues and next steps. Prefer |
| 68 | +copying resources into the body of the commit over providing external links. |
| 69 | +Structure large commit messages with headers, references etc. Remember, however, |
| 70 | +that the commit message is always going to be rendered in plain text. |
| 71 | + |
| 72 | +Use the commit footer to place commit metadata. The footer is the last block of |
| 73 | +contiguous text in the message. It is separated from the body by one or more |
| 74 | +blank lines, and as such cannot contain any blank lines. Lines in the footer are |
| 75 | +of the form: |
| 76 | + |
| 77 | +``` |
| 78 | +Key: Value |
| 79 | +``` |
| 80 | + |
| 81 | +When a commit has related issues or commits, explain the relation in the message |
| 82 | +body. You should also leave an `Issue` tag in the footer. For example: |
| 83 | + |
| 84 | +``` |
| 85 | +Correct race in frobnicator |
| 86 | +
|
| 87 | +This patch eliminates the race condition in issue #1234. |
| 88 | +
|
| 89 | +Issue: #1234 |
| 90 | +``` |
| 91 | + |
| 92 | +Sign off on your commit in the footer. By doing this, you assert original |
| 93 | +authorship of the commit and that you are permitted to contribute it. This can |
| 94 | +be automatically added to your commit by passing `-s` to `git commit`, or by |
| 95 | +manually adding the following line to the footer of the commit. |
| 96 | + |
| 97 | +``` |
| 98 | +Signed-off-by: Full Name <email> |
| 99 | +``` |
| 100 | + |
| 101 | +Remember, if a blank line is found anywhere after the `Signed-off-by` line, the |
| 102 | +`Signed-off-by:` will be considered outside of the footer, and will fail the |
| 103 | +automated Signed-off-by validation. The email used to sign off the commit must |
| 104 | +be the same, including case-sensitivity, as the one used to sign the Eclipse ECA, |
| 105 | +or your commit will fail IP validation. |
| 106 | + |
| 107 | +It is important that you read and understand the legal considerations found |
| 108 | +below when signing off or contributing any commit. |
| 109 | + |
| 110 | +### Example commits |
| 111 | + |
| 112 | +Here is an example of a *good* commit: |
| 113 | + |
| 114 | +``` |
| 115 | +Update and expand the commit guidelines |
| 116 | +
|
| 117 | +Elaborate on the style guidelines for commit messages. These new |
| 118 | +style guidelines reflect the conversation found in #124. |
| 119 | +
|
| 120 | +The guidelines are changed to: |
| 121 | +- Provide guidance on how to write a good first line. |
| 122 | +- Elaborate on formatting requirements. |
| 123 | +- Relax the advice on using issues for nontrivial commits. |
| 124 | +- Move issue references from the first line to the message footer. |
| 125 | +- Encourage contributors to put more information into the commit |
| 126 | + message. |
| 127 | +
|
| 128 | +Issue: #124 |
| 129 | +Signed-off-by: Robert Young <[email protected]> |
| 130 | +``` |
| 131 | + |
| 132 | +The first line is meaningful and imperative. The body contains enough |
| 133 | +information that the reader understands the why and how of the commit, and its |
| 134 | +relation to any issues. The issue is properly tagged and the commit is signed |
| 135 | +off. |
| 136 | + |
| 137 | +The following is a *bad* commit: |
| 138 | + |
| 139 | +``` |
| 140 | +FIX #124: Changing a couple random things in CONTRIBUTING.md. |
| 141 | +Also, there are some bug fixes in the thread library. |
| 142 | +``` |
| 143 | + |
| 144 | +The commit rolls unrelated changes together in a very bad way. There is not |
| 145 | +enough information for the commit message to be useful. The first line is not |
| 146 | +meaningful or imperative. The message is not formatted correctly, the issue is |
| 147 | +improperly referenced, and the commit is not signed off by the author. |
| 148 | + |
| 149 | +### Other resources for writing good commits |
| 150 | + |
| 151 | +- http://chris.beams.io/posts/git-commit/ |
| 152 | + |
| 153 | +## Legal considerations |
| 154 | + |
| 155 | +Please read the [Eclipse Foundation policy on accepting contributions via Git](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git). |
| 156 | + |
| 157 | +Your contribution cannot be accepted unless you have a signed [ECA - Eclipse Foundation Contributor Agreement](http://www.eclipse.org/legal/ECA.php) in place. If you have an active signed Eclipse CLA |
| 158 | +([the CLA was updated by the Eclipse Foundation to become the ECA in August 2016](https://mmilinkov.wordpress.com/2016/08/15/contributor-agreement-update/)), |
| 159 | +then that signed CLA is sufficient. You will have to sign the ECA once your CLA expires. |
| 160 | + |
| 161 | +Here is the checklist for contributions to be _acceptable_: |
| 162 | + |
| 163 | +1. [Create an account at Eclipse](https://dev.eclipse.org/site_login/createaccount.php). |
| 164 | +2. Add your GitHub user name in your account settings. |
| 165 | +3. [Log into the project's portal](https://projects.eclipse.org/) and sign the ["Eclipse ECA"](https://projects.eclipse.org/user/sign/cla). |
| 166 | +4. Ensure that you [_sign-off_](https://wiki.eclipse.org/Development_Resources/Contributing_via_Git#Signing_off_on_a_commit) your Git commits. |
| 167 | +5. Ensure that you use the _same_ email address as your Eclipse account in commits. |
| 168 | +6. Include the appropriate copyright notice and license at the top of each file. |
| 169 | + |
| 170 | +Your signing of the ECA will be verified by a webservice called 'ip-validation' |
| 171 | +that checks the email address that signed-off on your commits has signed the |
| 172 | +ECA. **Note**: This service is case-sensitive, so ensure the email that signed |
| 173 | +the ECA and that signed-off on your commits is the same, down to the case. |
| 174 | + |
| 175 | +### Copyright Notice and Licensing Requirements |
| 176 | + |
| 177 | +**It is the responsibility of each contributor to obtain legal advice, and |
| 178 | +to ensure that their contributions fulfill the legal requirements of their |
| 179 | +organization. This document is not legal advice.** |
| 180 | + |
| 181 | +Eclipse OpenJ9 is dual-licensed under the Eclipse Public License v2.0 and the |
| 182 | +Apache License v2.0. Any previously unlicensed contribution should be released |
| 183 | +under the same license. |
| 184 | + |
| 185 | +* If you wish to contribute code under a different license, you must consult |
| 186 | + with a project lead before contributing. |
| 187 | +* For any scenario not covered by this document, please discuss the copyright |
| 188 | + notice and licensing requirements with a project before contributing. |
| 189 | + |
| 190 | +The template for the copyright notice and dual-license is as follows: |
| 191 | +``` |
| 192 | +/******************************************************************************* |
| 193 | + * Copyright (c) %s, %s IBM Corp. and others |
| 194 | + * |
| 195 | + * This program and the accompanying materials are made available under |
| 196 | + * the terms of the Eclipse Public License 2.0 which accompanies this |
| 197 | + * distribution and is available at https://www.eclipse.org/legal/epl-2.0/ |
| 198 | + * or the Apache License, Version 2.0 which accompanies this distribution and |
| 199 | + * is available at https://www.apache.org/licenses/LICENSE-2.0. |
| 200 | + * |
| 201 | + * This Source Code may also be made available under the following |
| 202 | + * Secondary Licenses when the conditions for such availability set |
| 203 | + * forth in the Eclipse Public License, v. 2.0 are satisfied: GNU |
| 204 | + * General Public License, version 2 with the GNU Classpath |
| 205 | + * Exception [1] and GNU General Public License, version 2 with the |
| 206 | + * OpenJDK Assembly Exception [2]. |
| 207 | + * |
| 208 | + * [1] https://www.gnu.org/software/classpath/license.html |
| 209 | + * [2] http://openjdk.java.net/legal/assembly-exception.html |
| 210 | + * |
| 211 | + * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 |
| 212 | + *******************************************************************************/ |
| 213 | +``` |
0 commit comments