1. Introduction

The aim of this document is to present the OperatorFabric community, its code of conduct and to welcome contributors!

2. Contributing

Thank you for your interest !

We can’t stress enough that feedback, discussions, questions and contributions on OperatorFabric are very much appreciated. However, because the project is still in its early stages, we’re not fully equipped for any of it yet, so please bear with us while the contribution process and tooling are sorted out.

2.1. Code of Conduct

This project and everyone participating in it is governed by the OperatorFabric Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opfab_AT_lists.lfenergy.org.

2.2. License and Developer Certificate of Origin

OperatorFabric is an open source project licensed under the Mozilla Public License 2.0. By contributing to OperatorFabric, you accept and agree to the terms and conditions for your present and future contributions submitted to OperatorFabric.

The project also uses a mechanism known as a Developer Certificate of Origin (DCO) to ensure that we are legally allowed to distribute all the code and assets for the project. A DCO is a legally binding statement that asserts that you are the author of your contribution, and that you wish to allow OperatorFabric to use your work.

Contributors sign-off that they adhere to these requirements by adding a Signed-off-by line to commit messages. All commits to any repository of the OperatorFabric organization have to be signed-off like this:

This is my commit message.

Signed-off-by: John Doe <john.doe@email-provider.com>

You can write it manually but Git has a -s command line option to append it automatically to your commit message:

$ git commit -s -m 'This is my commit message'

Note that in the future a check will be performed during the integration, making sure all commits in the Pull Request contain a valid Signed-off-by line.

2.3. How Can I Contribute ?

These processes and templates have been adapted from the ones defined by the PowSyBl project.

2.3.1. Reporting Bugs and Suggesting Enhancements

Work in Progress

2.3.2. Contributing Code

Code Guidelines

  • We don’t mention specific authors by name in each file (in Javadoc or in the documentation for example), so has not to have to maintain these mentions (since this information is tracked by git anyway).

  • If you are working on a JIRA issue:

    • Please name your branch with the corresponding JIRA issue ID: OC-XXX

    • Start all your commit messages with [OC-XXX]

      This allows the branch, PR and commits to be directly accessible from the JIRA issue.

  • Before submitting your PR, please rebase your branch against the current master to minimize conflicts when merging.

    git checkout OC-XXX
git fetch
git rebase origin/master

  • Before submitting your PR, please squash/fix your commits so as to reduce the number of commits and comment them accordingly. In the end, the division of changes into commits should make the PR easier to understand and review.

  • Feel free to add a copyright header (on top of the existing ones) to files you create or amend. See src/main/headers for examples.

Contribution Process

Code Contribution is tracked as GitHub 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:

  • Maintain the quality of the project

  • Fix issues that are important to users

  • Allow everyone from the community to take part in the discussions, to reach the best possible solution

  • Make the review by OperatorFabric maintainers as efficient as possible

Please follow these steps to have your contribution considered by the maintainers:

  1. Fill in all the required information in the template.

  2. Request a GitHub review by one of the core developers

  3. Take their review into account or discuss the requested changes. Please don’t take criticism personally, it is normal to iterate on this step several times.

  4. Repeat step 3 until the pull request is merged!

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:

  • All tests in the test suite pass

  • Checkstyle and SonarCloud report no violations (coming soon)

  • The code coverage is high enough (currently about 85%) (coming soon)

2.4. Project Governance

2.4.1. Project Owner

OperatorFabric is part of the LF Energy Foundation, a project of the Linux Foundation that supports open source innovation projects within the energy and electricity sectors.

2.4.2. Committers

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.

2.4.3. Technical Steering Committee

The Technical Steering Committee (TSC) is composed of voting members elected by the active Committers as described in the project’s Technical Charter.

OperatorFabric TSC voting members are:

Boris Dolley will chair the TSC, with Hanae Safi as his deputy.

2.4.4. Contributors

Contributors include anyone in the technical community that contributes code, documentation, or other technical artifacts to the project.

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.

2.5. Communication channels

In addition to GitHub we have set up:

2.5.1. Website: opfab.org

Our website contains all the documentation and resources we’re currently working on. Here is what we aim to provide:

  • Architecture documentation

  • REST API documentation

  • Reference documentation for each component

  • Javadoc/Compodoc for each component

  • Tutorials and QuickStart guides and videos

This documentation is our priority right now so future contributors can quickly find their way around the project. Needless to say, it’s a work in progress so feel free to tell us what you feel is missing or what type of documentation you would be interested in as a contributor.

We also use this website to broadcast any news we have about the project so don’t hesitate to subscribe to the RSS feed on the home page to be informed of any update.

2.5.2. Spectrum Community : spectrum.chat/opfab

If you would like to join the discussions regarding OperatorFabric, please join our community on Spectrum!

Regarding issue tracking, our Jira platform should be open soon.

2.5.3. LF Energy Mailing Lists

Several mailing lists have been created by LF Energy for the project, please feel free to subscribe to the ones you could be interested in:

And if you’re interested in LF Energy in general: LF Energy General Discussion

2.5.4. JIRA

3. Contributor Covenant Code of Conduct

3.1. Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

3.2. Our Standards

Examples of behavior that contributes to creating a positive environment include:

  • Using welcoming and inclusive language

  • Being respectful of differing viewpoints and experiences

  • Gracefully accepting constructive criticism

  • Focusing on what is best for the community

  • Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

  • The use of sexualized language or imagery and unwelcome sexual attention or advances

  • Trolling, insulting/derogatory comments, and personal or political attacks

  • Public or private harassment

  • Publishing others' private information, such as a physical or electronic address, without explicit permission

  • Other conduct which could reasonably be considered inappropriate in a professional setting

3.3. Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

3.4. Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

3.5. Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at powsybl.ddl@rte-france.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

3.6. Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq