Currently v0.0.1
© 2024. All rights reserved.
Currently v0.0.1
© 2024. All rights reserved.
First off, thanks for taking the time to contribute!
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.
License and Developer Certificate of Origin
This project applies the LF Energy Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project’s Technical Steering Committee CoMPAS-tsc@lists.lfenergy.org.
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.
All contributions to this project are licensed under the license stipulated at the corresponding sub-repository. Except where otherwise explicitly indicated, CoMPAS is an open source project licensed under the Apache License, version 2.0.
The project requires the use of the Developer Certificate of Origin (DCO). 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.
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.
Here is an example Signed-off-by line, that indicates the contributor accepts the DCO:
This is my commit message.
Signed-off-by: Name Surname <name.surname@entity.com>
You can write it manually but Git even has a -s command line option to append this automatically to your commit message:
$ git commit -s -m 'This is my commit message'
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.
Online community refinement sessions can be scheduled ad-hoc e.g. via Slack. Feedback on stories/features can be put in the Github issue.
Topics to refine can be shared and published on the #compas channel on our LFEnergy Slack. You can ask feedback upfront as well.
Everybody can suggest topics for the refinement. To do this, join the LFEnergy Slack if not already, and put your topics in the #compas channel. You can just do this by writing a message like “I want to add something to the refinement this Monday, namely…” or add a comment to the already prepared topics if available (see Prepared topics).
Bugs and enhancement suggestions are tracked as GitHub issues. Create an issue in the repository where it belongs (an issue about the CIM to IEC 61850 mapping belongs in the CIM Mapping repository for example) and provide the following information by filling in the template, which is either an issue or a bug.
When an issue is created, it is automatically being added to the To do column of the specific repository. This means it’s added, but not yet refined. Every monday at 10AM CET, there is a Community Refinement (see our mailing list calendar, everybody can join) where issues are being discussed that are not refined yet. Your issue is one of them.
Once it’s accepted and refined, it goes to the Ready for development column and it’s ready to be implemented/fixed.
Before creating bug reports or suggesting enhancement, please perform a cursory search to see if the problem has already been reported. You can add a search term to the upper left search bar. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.
When in doubt, ask your question on our LFEnergy slack in the #compas channel. Or you can contact the team directly to talk about your ideas at CoMPAS-dev@lists.lfenergy.org.
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.
Code Contribution is tracked as GitHub Pull Requests. Crafting a good pull request takes time and energy, but we will help as much as we can, but be prepared to follow our iterative process. The iterative process has several goals:
Please follow these steps to have your contribution considered by the maintainers:
Continuous integration is set up 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:
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 example the Eclipse IDE.
Before finishing a requirement, you need to check if everything is done for that particular requirement. For that, we have a Definition of Done; the DoD decides when a requirement is really done.
Note: A Definition of Done is not a static list. It can be modified any time, if people feel like corrections should be made.
Current Definition of Done:
Before you start your coding journey within the CoMPAS project, there are some things we have to talk about. Some things that will make your start a little easier! On the developing page information about tooling can be found.
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.
When the Open Community Calls are taking place, can be found at the General CoMPAS mailing list calendar.
The agendas can be found at the LF Energy wiki.
If you have something to add, please add it to the agenda and notify everyone on Slack!
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!
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!
A good (open source) project requires documentation. We have two places for our documentation
LF Energy has it’s own CoMPAS specific Wiki. This is the place for documenation about CoMPAS in general (like roadmap and the community call agendas).
For all architecture and technology choices (for example frameworks, build tools, database choices, etcetera), please check the source code (duh!) and our CoMPAS Architecture GitHub Pages.
Copyright and license information is done on per-file basis. We use the specification of REUSE to ensure that copyright information of the project is clear and can be analyzed in an automated fashion.
Every source code repository within CoMPAS has a GitHub Action for checking against the REUSE specification.
For more information, check the Copyright Guidelines section.
For managing the CoMPAS issues created in all the separate repositories, we use the Projects Board of Github. CoMPAS uses 2 different Project Boards: One for Pull Requests and one for the Issues.
When creating Pull Requests or Issues, it will automatically create issues or Pull Requests on the Project Boards. This is done by the Automate Projects GitHub Action (take a look at the action from the Data Service for example). Changing the status of Issues / Pull Requests is also handled automatically by the GitHub Action.
Issues and Pull Requests can be moved on both the Project Boards and on the boards of the specific repository itself. It synchronizes automatically.
This site is provided as a GitHub pages site. The content is maintained and edited on GitHub in the directory “docs”. Contributors are only allowed to contribute by editing the content on GitHub and must do so by presenting their modifications as pull-request to the community. The diagrams on this page are created using DrawIO and follow Unified Modeling Language (UML). The drawIO design file is available on this site: /blob-files/CoMPAS.drawio. Modification made to UML diagrams on this site must be made in this file and the modified file must be part of the pull request.