|
| 1 | +# Contributing to the Project |
| 2 | + |
| 3 | +Thank you for your interest in contributing to |
| 4 | +the [Eclipse Dataspace Components](https://projects.eclipse.org/projects/technology.edc)! |
| 5 | + |
| 6 | +## Table of Contents |
| 7 | + |
| 8 | +* [Code Of Conduct](#code-of-conduct) |
| 9 | +* [Eclipse Contributor Agreement](#eclipse-contributor-agreement) |
| 10 | +* [How to Contribute](#how-to-contribute) |
| 11 | + * [Discuss](#discuss) |
| 12 | + * [Create an Issue](#create-an-issue) |
| 13 | + * [Submit a Pull Request](#submit-a-pull-request) |
| 14 | + * [Report on Flaky Tests](#report-on-flaky-tests) |
| 15 | +* [Project and Milestone Planning](#project-and-milestone-planning) |
| 16 | + * [Milestones](#milestones) |
| 17 | + * [Projects](#projects) |
| 18 | + * [Releases](#releases) |
| 19 | +* [Contact Us](#contact-us) |
| 20 | + |
| 21 | +Find more information here: |
| 22 | +- [Adoptions](contributing/adoption.md) |
| 23 | +- [PR Etiquette](contributing/pr_etiquette.md) |
| 24 | + |
| 25 | +## Code Of Conduct |
| 26 | + |
| 27 | +See the [Eclipse Code Of Conduct](https://www.eclipse.org/org/documents/Community_Code_of_Conduct.php). |
| 28 | + |
| 29 | +## Eclipse Contributor Agreement |
| 30 | + |
| 31 | +Before your contribution can be accepted by the project, you need to create and electronically sign |
| 32 | +a [Eclipse Contributor Agreement (ECA)](http://www.eclipse.org/legal/ecafaq.php): |
| 33 | + |
| 34 | +1. Log in to the [Eclipse foundation website](https://accounts.eclipse.org/user/login/). You will |
| 35 | + need to create an account within the Eclipse Foundation if you have not already done so. |
| 36 | +2. Click on "Eclipse ECA", and complete the form. |
| 37 | + |
| 38 | +Be sure to use the same email address in your Eclipse Account that you intend to use when you commit |
| 39 | +to GitHub. |
| 40 | + |
| 41 | +## How to Contribute |
| 42 | + |
| 43 | +### Discuss |
| 44 | + |
| 45 | +If you want to share an idea to further enhance |
| 46 | +the project or discuss potential use cases, please feel free to create a discussion. |
| 47 | +- For detailed and repository-specific topics, use the [GitHub discussions](https://github.com/features/discussions) |
| 48 | + in a repository. |
| 49 | +- For high-level and general questions or discussions (e.g., relations to Gaia-X, plannings), or if you |
| 50 | + want to share use case related ideas or receive feedback from the community, please use the [GitHub |
| 51 | + organization's discussions](https://github.com/orgs/eclipse-edc/discussions). |
| 52 | + |
| 53 | +If you feel there is a bug or an issue, contribute to the discussions in **existing issues**, otherwise |
| 54 | +[create a new issue](#create-an-issue). |
| 55 | + |
| 56 | +### Create an Issue |
| 57 | + |
| 58 | +If you have identified a bug or want to formulate a working item that you want to concentrate on, |
| 59 | +feel free to create a new issue at the repository's corresponding GitHub Issues page. |
| 60 | + |
| 61 | +Before doing so, please consider searching for potentially suitable existing issues: https://github.com/eclipse-edc/.../issues?q=is%3Aissue+is%3Aopen. |
| 62 | + |
| 63 | +We also use [GitHub's default label set](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) |
| 64 | +extended by custom ones to classify issues and improve findability. |
| 65 | + |
| 66 | +If an issue appears to cover changes that will have a (huge) impact on the code base and needs to |
| 67 | +first be discussed, or if you just have a question regarding the usage of the software, please |
| 68 | +create a discussion before raising an issue. |
| 69 | + |
| 70 | +Please note that if an issue covers a topic or the response to a question that may be interesting |
| 71 | +for other developers or contributors, or for further discussions, it should be converted to a |
| 72 | +discussion and not be closed. |
| 73 | + |
| 74 | +### Adhere to Coding Style Guide |
| 75 | + |
| 76 | +We aim for a coherent and consistent code base, thus the coding style detailed in the |
| 77 | +[styleguide](developer/contributing/styleguide.md) should be followed. |
| 78 | + |
| 79 | +### Submit a Pull Request |
| 80 | + |
| 81 | +In addition to the contribution guideline made available in the |
| 82 | +[Eclipse project handbook](https://www.eclipse.org/projects/handbook/#contributing), |
| 83 | +we would appreciate if your pull request applies to the following points: |
| 84 | + |
| 85 | +* Conform to [Pull-Request Etiquette](contributing/pr_etiquette.md) |
| 86 | + |
| 87 | +* Always apply the following copyright header to specific files in your work replacing the fields |
| 88 | + enclosed by curly brackets "{}" with your own identifying information. (Don't include the curly |
| 89 | + brackets!) Enclose the text in the appropriate comment syntax for the file format. |
| 90 | + |
| 91 | + ```text |
| 92 | + Copyright (c) {year} {owner}[ and others] |
| 93 | +
|
| 94 | + This program and the accompanying materials are made available under the |
| 95 | + terms of the Apache License, Version 2.0 which is available at |
| 96 | + https://www.apache.org/licenses/LICENSE-2.0 |
| 97 | +
|
| 98 | + SPDX-License-Identifier: Apache-2.0 |
| 99 | +
|
| 100 | + Contributors: |
| 101 | + {name} - {description} |
| 102 | + ``` |
| 103 | +
|
| 104 | +* The git commit messages should comply to the following format: |
| 105 | + ``` |
| 106 | + <prefix>(<scope>): <description> |
| 107 | + ``` |
| 108 | +
|
| 109 | + Use the [imperative mood](https://github.com/git/git/blob/master/Documentation/SubmittingPatches) |
| 110 | + as in "Fix bug" or "Add feature" rather than "Fixed bug" or "Added feature" and |
| 111 | + [mention the GitHub issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) |
| 112 | + e.g. `chore(transfer process): improve logging`. |
| 113 | +
|
| 114 | + All committers and all commits, are bound to |
| 115 | + the [Developer Certificate of Origin.](https://www.eclipse.org/legal/DCO.php) |
| 116 | + As such, all parties involved in a contribution must have valid ECAs. Additionally, commits can |
| 117 | + include a ["Signed-off-by" entry](https://wiki.eclipse.org/Development_Resources/Contributing_via_Git). |
| 118 | + |
| 119 | +* Add meaningful tests to verify your submission acts as expected. |
| 120 | +
|
| 121 | +* Where code is not self-explanatory, add documentation providing extra clarification. |
| 122 | +
|
| 123 | +* Add documentation files to new modules. See [here](#add-documentation) for more details. |
| 124 | +
|
| 125 | +* If a new module has been added or a significant part of the code has been changed, and you should |
| 126 | + or want to be seen as the contact person for any further changes, please add appropriate |
| 127 | + information to the [CODEOWNERS](https://github.com/eclipse-edc/Connector/blob/main/CODEOWNERS) |
| 128 | + file. You can find instructions on how to do this at <https://help.github.com/articles/about-codeowners/>. |
| 129 | + Please note that this file does not represent all contributions to the code. What persons and organizations |
| 130 | + actually contributed to each file can be seen on GitHub and is documented in the license headers. |
| 131 | +
|
| 132 | +* PR descriptions should use the current [PR template](docs/submodule/GitHub/.github/PULL_REQUEST_TEMPLATE.md) |
| 133 | +
|
| 134 | +* Submit a draft pull request at early-stage and add people previously working on the same code as |
| 135 | + reviewer. Make sure automatic checks pass before marking it as "ready for review": |
| 136 | +
|
| 137 | + * _Intellectual Property Validation_ verifying the [Eclipse CLA](#eclipse-contributor-agreement) |
| 138 | + has been signed as well as commits have been signed-off and |
| 139 | + * _Continuous Integration_ performing various test conventions. |
| 140 | +
|
| 141 | +### Stale issues and PRs |
| 142 | +
|
| 143 | +In order to keep our backlog clean we are using a bot that helps us label and eventually close old issues and PRs. The |
| 144 | +following table shows the particular timings. |
| 145 | +
|
| 146 | +| | `stale` after | closed after days `stale` | |
| 147 | +|------------------------|---------------|---------------------------| |
| 148 | +| Issue without assignee | 14 | 7 | |
| 149 | +| Issue with assignee | 28 | 7 | |
| 150 | +| PR | 7 | 7 | |
| 151 | +
|
| 152 | +Note that updating an issue, e.g. by commenting, will remove the `stale` label again and reset the counters. However, |
| 153 | +we ask the community **not to abuse** this feature (e.g. commenting "what's the status?" every X days would certainly |
| 154 | +be qualified as abuse). If an issue receives no attention, there usually |
| 155 | +are reasons for it. It is therefore advisable to clarify in advance whether any particular feature fits into EDC's |
| 156 | +planning schedule and roadmap. For that, we recommend opening a discussion. Discussions serve us as a system of record, that |
| 157 | +means we monitor them more closely, and do not close them automatically. |
| 158 | +
|
| 159 | +### Add Documentation |
| 160 | +
|
| 161 | +Every decision record, launcher, extension, or any type of module has to provide documentation that covers at least |
| 162 | +one markdown file with necessary information. Please find appropriate templates that should |
| 163 | +be used in [the templates directory](developer/templates/). |
| 164 | +
|
| 165 | +### Report on Flaky Tests |
| 166 | +
|
| 167 | +If you discover a randomly failing ("flaky") test, please take the time to check whether an issue for that already |
| 168 | +exists and if not, create an issue yourself, providing meaningful description and a link to the failing run. Please also |
| 169 | +label it with `Bug` and `FlakyTest`. Then assign it to whoever was the original author of the relevant piece of code or |
| 170 | +whoever worked on it last. If assigning the issue is not possible due to missing rights, please just comment and |
| 171 | +@mention the author/last editor. |
| 172 | +
|
| 173 | +Please do not just restart the run, as this would overwrite the results. If you need to, a better way of doing this is |
| 174 | +to push an empty commit. This will trigger another run. |
| 175 | +
|
| 176 | +```bash |
| 177 | +git commit --allow-empty -m "trigger CI" && git push |
| 178 | +``` |
| 179 | + |
| 180 | +If an issue labeled with `Bug` and `FlakyTest` is assigned to you, please prioritize addressing this issue as other people will be affected. |
| 181 | +We are taking the quality of our code very serious and reporting on flaky tests is an important step toward improvement |
| 182 | +in that area. |
| 183 | + |
| 184 | +## Non-code Contributions |
| 185 | + |
| 186 | +The following list shows examples of non-code contributions which, however, are not limited to: |
| 187 | + |
| 188 | +- Strengthen the EDC brand |
| 189 | + - Evangelizing the project |
| 190 | + - Developing community |
| 191 | +- Community education |
| 192 | + - Answering questions on GitHub, Discord, Youtube, etc. |
| 193 | + - Onboarding new contributors |
| 194 | + - Contribute to EDC docs |
| 195 | + - Doing hands-on sessions and demos |
| 196 | +- Outward-facing community work |
| 197 | + - Hosting meetups (Q&A) and general evangelism |
| 198 | + - Presentation of work to meetups |
| 199 | + - Social Media |
| 200 | + - Non-Documentation writing (Blogs, Articles, Interviews) |
| 201 | +- Branding/Visual Communication |
| 202 | + - Website management |
| 203 | + - Visuals (diagrams, infographic design, icon design) |
| 204 | +- Management of communication tools (at the discretion of project maintainers) |
| 205 | + - Mailing list moderation |
| 206 | + - Discord management |
| 207 | + - Calendar management |
| 208 | +- Event management |
| 209 | + - Host community events |
| 210 | + - Support summits and hackathons |
| 211 | + - Staffing EDC booths at conferences |
| 212 | + |
| 213 | +## Project and Milestone Planning |
| 214 | + |
| 215 | +We use milestones to set a common focus for a period of 6 to 8 weeks. |
| 216 | +The group of committers chooses issues based on customer needs and contributions we expect. |
| 217 | + |
| 218 | +### Milestones |
| 219 | + |
| 220 | +Milestones are organized at the [GitHub Milestones page](https://github.com/eclipse-edc/Connector/milestones). |
| 221 | +They are numbered in ascending order. There, contributors, users, and adopters can track the progress. |
| 222 | + |
| 223 | +Please note that the due date of a milestone does not imply any guarantee that all linked issued will |
| 224 | +be resolved by then. |
| 225 | + |
| 226 | +When closing the current milestone, issues that were not resolved within a milestone phase will be |
| 227 | +reviewed to evaluate their relevance and priority, before being assigned to the next milestone. |
| 228 | + |
| 229 | +#### Issues |
| 230 | + |
| 231 | +Every issue that should be addressed during a milestone phase is assigned to it by using the |
| 232 | +`Milestone` feature for linking both items. This way, the issues can easily be filtered by |
| 233 | +milestones. |
| 234 | + |
| 235 | +#### Pull Requests |
| 236 | + |
| 237 | +Pull requests are not assigned to milestones as their linking to issues is sufficient to track |
| 238 | +the relations and progresses. |
| 239 | + |
| 240 | +### Projects |
| 241 | + |
| 242 | +The [GitHub Projects page](https://github.com/eclipse-edc/Connector/projects) |
| 243 | +provides a general overview of the project's working items. Every new issue is automatically assigned |
| 244 | +to the ["Dataspace Connector" project](https://github.com/orgs/eclipse-edc/projects/3). |
| 245 | +It can be unassigned or moved to any other project that is provided. |
| 246 | + |
| 247 | +In every project, an issue passes four stages: `Backlog`, `In progress`, `Review in progress`, and `Done`, |
| 248 | +independent of their association to a specific milestone. |
| 249 | + |
| 250 | +### Releases |
| 251 | + |
| 252 | +Please find more information about our release approach [here](developer/releases.md). |
| 253 | + |
| 254 | +## Contact Us |
| 255 | + |
| 256 | +If you have questions or suggestions, do not hesitate to contact the project developers via |
| 257 | +the [project's "dev" list](https://dev.eclipse.org/mailman/listinfo/edc-dev). |
| 258 | + |
| 259 | +You may also want to join our [Discord server](https://discord.gg/n4sD9qtjMQ). |
| 260 | + |
| 261 | +There, we provide a biweekly meeting on fridays 2-3 p.m. (CET) to give any interested person the |
| 262 | +opportunity to get in touch with the committer team. We are meeting in the "general" voice channel. |
| 263 | +Find more details about the schedule [on GitHub](https://github.com/eclipse-edc/Connector/discussions/1303). |
| 264 | + |
| 265 | +_If you have a "contributor" or "committer" status, you will also have access to private channels._ |
0 commit comments