|
1 | 1 | # Contributing to CoMPAS |
2 | 2 |
|
3 | | -First off, thanks for taking the time to contribute! |
| 3 | +Go to the site [Contribution to CoMPAS](https://com-pas.github.io/contributing/) |
4 | 4 |
|
5 | | -The following is a set of guidelines for contributing to the CoMPAS project. These are mostly guidelines, sometimes rules. Use your best judgment, and feel free to propose changes to this document in a pull request. |
6 | | - |
7 | | -#### Table Of Contents |
8 | | - |
9 | | -[Code of Conduct](#code-of-conduct) |
10 | | - |
11 | | -[License and Developer Certificate of Origin](#license-and-developer-certificate-of-origin) |
12 | | - |
13 | | -[How Can I Contribute?](#how-can-i-contribute) |
14 | | - * [Reporting Bugs and Suggesting Enhancements](#reporting-bugs-and-suggesting-enhancements) |
15 | | - * [Contributing Code](#contributing-code) |
16 | | - * [Tools to contribute](#tools-to-contribute) |
17 | | - * [Definition of Done](#definition-of-done) |
18 | | - * [Copyright Guidelines](#definition-of-done) |
19 | | - * [How-to begin](#how-to-begin) |
20 | | - * [Github Project Boards](#github-project-boards) |
21 | | - |
22 | | -[Styleguides](#styleguides) |
23 | | - * [Copyright Guidelines](#copyright-guidelines) |
24 | | - |
25 | | -[Project Governance](#project-governance) |
26 | | - * [Project Owner](#project-owner) |
27 | | - * [Technical Charter](#technical-charter) |
28 | | - * [Committers](#committers) |
29 | | - * [Technical Steering Committee](#technical-steering-committee) |
30 | | - * [Contributors](#contributors) |
31 | | - |
32 | | -## Code of Conduct |
33 | | - |
34 | | -This project applies the [LF Energy Code of Conduct ](https://www.lfenergy.org/about/code-of-conduct/). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project's Technical Steering Committee [[email protected]](mailto:[email protected]). |
35 | | - |
36 | | -## License and Developer Certificate of Origin |
37 | | - |
38 | | -By contributing to the CoMPAS project, you accept and agree to the following terms and conditions for your present and future contributions submitted to CoMPAS. |
39 | | - |
40 | | -All contributions to this project are licensed under the license stipulated at the corresponding sub-repository. Except where otherwise explicitely indicated, CoMPAS is an open source project licensed under the [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0/). |
41 | | - |
42 | | -The project requires the use of the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). The DCO is a legally binding statement asserting that you are you have the right to submit your contribution and to license it under the project's applicable license. |
43 | | - |
44 | | -Contributors sign-off that they adhere to the term of the DCO by adding a ``Signed-off-by`` line to commit messages. The DCO sign-off must be attached to every contribution made by every contributor. |
45 | | - |
46 | | -Here is an example ``Signed-off-by`` line, that indicates the contributor accepts the DCO: |
47 | | - |
48 | | -```` |
49 | | -This is my commit message. |
50 | | -
|
51 | | -Signed-off-by: Name Surname <[email protected]> |
52 | | -```` |
53 | | -You can write it manually but Git even has a -s command line option to append this automatically to your commit message: |
54 | | -```` |
55 | | -$ git commit -s -m 'This is my commit message' |
56 | | -```` |
57 | | - |
58 | | -Note that checks will be performed during the integration in order to require that commits in a Pull Request contain valid ``Signed-off-by`` lines. |
59 | | - |
60 | | -## How Can I Contribute? |
61 | | - |
62 | | -### Reporting Bugs and Suggesting Enhancements |
63 | | - |
64 | | -Bugs and enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue and provide the following information by filling in [the template](ISSUE_TEMPLATE.md). |
65 | | - |
66 | | -Before creating bug reports or suggesting enhancement, please **perform a [cursory search](https://github.com/search?q=+is%3Aissue+user%3Acom-pas)** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one.. |
67 | | - |
68 | | -You can also contact the team directly to talk about your ideas at [[email protected]](mailto:[email protected]). |
69 | | - |
70 | | -> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. |
71 | | -
|
72 | | -### Contributing Code |
73 | | - |
74 | | -Code Contribution is tracked as [GitHub Pull Requests](https://help.github.com/en/articles/about-pull-requests). Crafting a good pull request takes time and energy and we will help as much as we can, but be prepared to follow our iterative process. The iterative process has several goals: |
75 | | - |
76 | | -- maintain the software quality, |
77 | | -- fix problems that are important to users, |
78 | | -- engage the community in working toward the best possible software features, |
79 | | -- enable a sustainable system for maintainers to review contributions. |
80 | | - |
81 | | -Please follow these steps to have your contribution considered by the maintainers: |
82 | | - |
83 | | -1. Follow all instructions in [the template](PULL_REQUEST_TEMPLATE.md) |
84 | | -2. Follow the [styleguides](#styleguides) |
85 | | -3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing. |
86 | | -5. Request a GitHub review by one of the projects' Committers |
87 | | -6. Follow their instructions or discuss about the requested changes. Please don't take criticism personally, it is normal to iterate on this step several times. |
88 | | -7. Repeat step 6 until the pull request is merged! |
89 | | - |
90 | | -Continuous integration is setup to run on all branches automatically and will often report problems, so don't worry about getting everything perfect on the first try (SonarCloud Analysis is a notorious problem source). Until you add a reviewer, you can trigger as many builds as you want by amending your commits. The status checks enforce the following: |
91 | | - |
92 | | -- All tests in the test suite pass. |
93 | | -- Checkstyle and SonarCloud report no violations. |
94 | | -- The code coverage is high enough (currently about 80%). |
95 | | - |
96 | | -### Tools to contribute |
97 | | - |
98 | | -Continuous integration is setup automatically on all contributions. However, it's faster to iterate locally to fix problems than waiting for the status checks to finish. There are many tools that can be used to do the verifications that are enforced by all status checks. The most simple and universal tool is maven, but IDE integrations can be used to get more immediate feedback. Most of the team uses IntelliJ IDEA, but others IDEs can be used, for exemple the Eclipse IDE. |
99 | | - |
100 | | -### Definition of Done |
101 | | - |
102 | | -Before finishing a requirement, you need to check if everything is done for that particular requirement. |
103 | | -For that, we have a Definition of Done; the DoD decides when a requirement is really done. |
104 | | - |
105 | | -Note: A Defintion of Done is not a static list. It can be modified any time, if people feel like corrections should be made. |
106 | | - |
107 | | -Current Definition of Done: |
108 | | -- Assumptions of requirements are met. |
109 | | -- Required documentation is done. |
110 | | -- (Software) Requirement is accepted and got a thumbs up from the Maintainer via an accepted Pull Request. |
111 | | -- (Software) The build succeeds without failures. |
112 | | -- (Software) All tests in the test suite pass. |
113 | | -- (Software) Code style checks report no violations. |
114 | | -- (Software) Code coverage is high enough (a minimum of 80% is coveraged). |
115 | | -- (Software) If applicable, the added Unit Test is written, executed and passed. |
116 | | -- (Software) Security analysis (vulnerability detection) doesn't spot unaddressed issues. |
117 | | - |
118 | | -### How-to begin |
119 | | - |
120 | | -Before you start your coding journey within the CoMPAS project, there are some things we have to talk about. |
121 | | -Some things that will make your start a little bit easier! |
122 | | -On the [developing](DEVELOPING.md) page information about tooling can be found. |
123 | | - |
124 | | -#### Open Community Calls |
125 | | -It's good to know that every other monday, we are having a so called Open Community Call. Everyone participating in the CoMPAS project can join and talk about and ask question about the CoMPAS project. |
126 | | - |
127 | | -When the Open Community Calls are taking place, can be found at the [General CoMPAS mailing list calendar](https://lists.lfenergy.org/g/CoMPAS/calendar). |
128 | | - |
129 | | -The agendas can be found at the [LF Energy wiki](https://wiki.lfenergy.org/display/HOME/CoMPAS+Community+Calls). |
130 | | - |
131 | | -If you have something to add, please add it to the agenda and notify everyone on Slack! |
132 | | - |
133 | | -#### Slack channel |
134 | | -One of the first important things, is to meet the community. Feel free to introduce yourself by joining the channel 'compas' on [LF Energy Slack](https://slack.lfenergy.org/)! |
135 | | - |
136 | | -The Slack channel is the first communication platform within the CoMPAS project (besides email and the Github platform), so if you need help for example you can use Slack! |
137 | | - |
138 | | -#### Documenting |
139 | | -A good (open source) project requires documentation. |
140 | | -We have two places for our documentation |
141 | | - |
142 | | -##### LF Energy Wiki |
143 | | -LF Energy has it's own [CoMPAS specific Wiki](https://wiki.lfenergy.org/display/HOME/CoMPAS). This is the place for documenation about CoMPAS in general (like roadmap and the community call agendas). |
144 | | - |
145 | | -#### Architecture and technologies |
146 | | -For all architecture and technology choices (for example frameworks, build tools, database choices, etcetera), |
147 | | -please check the source code (duh!) and our [CoMPAS Architecture Github Pages](https://com-pas.github.io/compas-architecture/). |
148 | | - |
149 | | -#### Copyright and Licensing |
150 | | -Copyright and license information is done on per-file basis. We use the specification of [REUSE](https://reuse.software/spec/) |
151 | | -to ensure that copyright information of the project is clear and can be analuzed in an automated fashion. |
152 | | - |
153 | | -Every source code repository within CoMPAS has a Github Action for checking against the REUSE specification. |
154 | | - |
155 | | -For more information, check the [Copyright Guidelines](#copyright-guidelines) section. |
156 | | - |
157 | | - |
158 | | -### Github Project Boards |
159 | | -For managing the CoMPAS issues created in all the separate repositories, we use the [Projects Board](https://github.com/orgs/com-pas/projects) of Github. |
160 | | -CoMPAS uses 2 different Project Boards: One for [Pull Requests](https://github.com/orgs/com-pas/projects/2) and one for the [Issues](https://github.com/orgs/com-pas/projects/1). |
161 | | - |
162 | | -When creating Pull Requests or Issues, it will automatically create issues or Pull Requests on the Project Boards. |
163 | | -This is done by the Automate Projects Github Action (take a look at the [action from the Data Service](https://github.com/com-pas/compas-scl-data-service/blob/develop/.github/workflows/automate_projects.yml) for example). |
164 | | -Changing the status of Issues / Pull Requests is also handled automatically by the Github Action. |
165 | | - |
166 | | -Issues and Pull Requests can be moved on both the Project Boards and on the boards of the specific repository itself. It synchronizes automatically. |
167 | | - |
168 | | -## Styleguides |
169 | | - |
170 | | -### Copyright Guidelines |
171 | | - |
172 | | -Contributing to the CoMPAS project also requires to use correct copyright headers in source files. |
173 | | - |
174 | | -For each CoMPAS repository, we created / will create a Github Action featuring [REUSE](https://reuse.software/). REUSE is a piece of software which checks for correct copyright information in files defined in a [specification](https://reuse.software/spec/). The specification is based on best practices and the use of [SPDX](https://spdx.dev/) identifiers. |
175 | | - |
176 | | -Example Alliander copyright header for Java files: |
177 | | -```Java |
178 | | -// SPDX-FileCopyrightText: 2020 Alliander N.V. |
179 | | -// |
180 | | -// SPDX-License-Identifier: Apache-2.0 |
181 | | -``` |
182 | | - |
183 | | -Every commit on a Pull Request is being scanned by REUSE. If it fails, the pull requests cannot be merged. |
184 | | - |
185 | | -For more tips on using REUSE (for example with a small command line tool), check the [Tips: Copyright & Licensing](https://wiki.lfenergy.org/pages/viewpage.action?pageId=10996220) wiki page. |
186 | | - |
187 | | -### English language convention |
188 | | - |
189 | | -The convention for all the project's documents, including code documentation, website, is to write American English. |
190 | | -A list of spelling differences between British and American English is available |
191 | | -[here](https://www.britishcouncilfoundation.id/en/english/articles/british-and-american-english) for example. |
192 | | - |
193 | | -## Project Governance |
194 | | - |
195 | | -#### Project Owner |
196 | | - |
197 | | -CoMPAS is part of the [LF Energy Foundation](https://www.lfenergy.org/), a project of The Linux Foundation that supports open source innovation projects within the energy and electricity sectors. |
198 | | - |
199 | | -#### Technical Charter |
200 | | - |
201 | | -The Project's [Technical Charter](CoMPAS%20Technical%20Charter%207-6-2020.pdf) sets forth the responsibilities and procedures for technical contribution to, and oversight of, the COMPAS Project. |
202 | | - |
203 | | -#### Committers |
204 | | - |
205 | | -Committers are contributors who have made several valuable contributions to the project and are now relied upon to both write code directly to the repository and screen the contributions of others. In many cases they are programmers but it is also possible that they contribute in a different role. Typically, a committer will focus on a specific aspect of the project, and will bring a level of expertise and understanding that earns them the respect of the community and the project owner. |
206 | | - |
207 | | -#### Technical Steering Committee |
208 | | - |
209 | | -The Technical Steering Committee (TSC) is composed of voting members elected by the active Committers as described in the project’s Technical Charter. The TSC is responsible for the technical direction of the project. |
210 | | - |
211 | | -#### Members |
212 | | -CoMPAS TSC voting members are: |
213 | | -- Norbert Armand (https://github.com/Norbert-armand) |
214 | | -- Frédéric Fousseret (https://github.com/FredFousPro) |
215 | | -- Mohamed Sylla (https://github.com/syllamoh) |
216 | | -- Stevan Vigouroux (https://github.com/SteVigGE) |
217 | | -- Sander Jansen (https://github.com/Sander3003) |
218 | | -- Rob Tjalma (https://github.com/Flurb) |
219 | | - |
220 | | -#### Voting |
221 | | -While the Project aims to operate as a consensus-based community, if any TSC decision requires a vote to move the Project forward, the voting members of the TSC will vote on a one vote per voting member basis. The simple majority is needed to approve proposals. |
222 | | -The preferred way to vote is to create a poll [here](https://lists.lfenergy.org/g/CoMPAS-tsc/addpoll). |
223 | | - |
224 | | -#### Responsibilities |
225 | | -The project is split into several repositories. There is at least one Committer in charge of each repository. By "in charge", we mean: |
226 | | -- best effort to review the pull request, |
227 | | -- best effort to resolve issues, |
228 | | -- building and publishing the releases, including writing the release notes and informing the community, |
229 | | -- in case of unability to perform the above tasks, the Committer in charge has to ask the TSC through the list [[email protected]](mailto:[email protected]) to find another Committer to review the pull request, resolve the issue or build and publish the release. |
230 | | - |
231 | | -Please refer to our [maintainers file](MAINTAINERS.md) for more details about our work division. |
232 | | - |
233 | | -#### Contributors |
234 | | - |
235 | | -Contributors include anyone in the technical community that contributes code, documentation, or other technical artifacts to the Project. |
236 | | - |
237 | | -Anyone can become a contributor. There is no expectation of commitment to the project, no specific skill requirements and no selection process. To become a contributor, a community member simply has to perform one or more actions that are beneficial to the project. |
0 commit comments