Grid eXchange Fabric (GXF) is a project of . LF Energy is part of the .

This is a guide to start contributing to the open smart grid platform project:

1. Make yourself comfortable with the open smart grid platform by e.g. installing it.

2. Read the documentation to get an idea of how the software works (architecture chapter), how the community works (this chapter).

3. Find an open issue to work on or fire an new issue.

4. Assign yourself to the issue and start contributing.

5. Start contributing by using the procedures mentioned in this chapter.

Developer tools, technical guidelines and continuous integration

Tools Used

The technology and tools used can be found in the section.

Code Guidelines and Code Tests

• To prevent formatting issues caused by using different IDEs, the formatting style for the code is based on with some extra additions based on the Eclipse based conventions that were already in use.

  Check the explanation of the as well as the instructions how to configure your idea to be able to format according to the conventions (available for and ).

• Follow approach for branching

Continuous Integration

All changes pushed to GitHub are built by our build server. Pull requests to master branch or development branch are also built. SonarQube performs static code analysis to help improve the quality level of the code base.

• : An open source continuous integration tool written in Java.

• : SonarQube is an open platform to manage code quality.

Technical Conventions and Rules for New Code

This project is engineered, built and tested using Domain Driven Design and Behaviour Driven Tests.

• Use the Frameworks, don't roll your own

• Single class, single responsibility

• Value objects are immutable

Development Guide per Component

Web Service Adapters

The web service adapters use Spring Web Service, contract first. JAXB is used to generate Java classes from the XSD's. All SOAP operations are bound to an endpoint. The incoming SOAP requests are authenticated by organization identification (plus certificates). Organization authorizations are checked for the desired operation. If the request is OK, a JMS message is sent to a domain adapter component.

Domain Adapters

Domain adapters contain business logic and persistence. Domain adapters process and forward the JMS message to the Core component.

Domain Components

Domain components contain entities and value objects.

Core

The Core component routes messages from domain adapter components to protocol adapter components and vice versa. Furthermore, it offers read-only database access for protocol adapter components.

Protocol Adapters

Protocol Adapter components translate a message from domain adapter components into a protocol message for a smart device. Protocol Adapter components send the protocol message to a smart device using a network connection. The response from the smart device is translated into a domain response message which will be sent to the Core components (which will route it to the domain adapter which issued the request).

OSLP

For the OSLP implementation, two components are used. The first component is the protocol adapter for the protocol. It can translate message into the protocol message for SSLD's. Second there's the signing-server component. It is responsible for signing the protocol message using the private key of the platform. The components communicate using a key-pair. The signing-server can handle multiple protocol adapter instances by utilizing a reply-to queue per protocol adapter instance. Since the protocol adapter component needs to be reachable from a network, it is a requirement that the private key may not be used by the protocol adapter directly. The signing server component can be deployed in such a way that no network access is available to this component, as the only coupling needed are the queues / the message broker.

Other Guides

Installation Guide

If a full installation is desired, have a look at our .

Create New Domain Guide

In order to add a new domain to OSGP, you can benefit from the information in the .

We invite everyone to participate in the development of the open smart grid platform. There are multiple ways to support the project.

• submit issues about bugs or requested features

• solve issues

• develop new features

• write or improve the documentation

This chapter contains all the non-technical and general technical knowledge for developers to start contributing.

If you want to get in touch to discuss non-technical subjects, send us an email to the LF energy GXF mailing list gxf@lists.lfenergy.org or open an issue on Github.

New Features

1. If there is a need (or wish!) for a new feature, add it as issue to Github. Please provide a full description about the background of the problem.

2. A developer can take on the issue and start working on it on voluntary base. If you need this feature and you have the money to pay for it, you can hire a developer and have the developer work on it. If open smart grid platform core components are involved, please discuss your change first with one of the developers/maintainers.

3. The developer makes a description on how he wants to fix the problem. Other developers can discuss the solution as well. If everybody agrees on the solution direction, the developer codes the solution and submits it (by sending in a pull request). The developer should also document the feature in the

4. The maintainer can check the code (or assign this to someone else) and merge it with upstream releases.

Bug tracking

1. Find out as much as possible about the bug before reporting it. Please check on GitHub/Jira whether the bug has already been reported. Also, look for logs, error messages etc. Please include as much information as possible background on the bug and submit the bug on Github or Jira.

2. The maintainer makes sure that somebody will look at the bug, check for duplicates and thank the contributor for sending in the bug. If the bug turns out to be a duplicate, the issue will be closed.

3. A developer will try to reproduce the bug and will look for the root cause. The developer adds his findings to the issue. If the developer cannot reproduce the bug, the developer will contact the user for more information or/and login into the user's system (when possible for the user/developer). If it's impossible to re-produce the bug, the issue will be closed.

Questions

If you have a question, please create an Github issue in the .

Report security issues

Due to the sensible nature of security issues e.g. zero days, we prefer a responsible disclosure. Security issues can be reported to .

Like the technical community as a whole, the open smart grid platform community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentor-ship, teaching, and connecting people.

Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.

This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.

This code of conduct applies to all spaces managed by the GXF project (a LF energy project). This includes IRC, the mailing lists, the issue tracker, DSF events, and any other forums created by the project team which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.

If you believe someone is violating the code of conduct, we ask that you report it by emailing the mailing list gxf@lists.lfenergy.org.

Be friendly and patient.

Be welcoming.

We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.

Be considerate.

Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.

Be respectful.

Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the open smart grid platform community should be respectful when dealing with other members as well as with people outside the open smart grid platform community.

Be careful in the words that you choose.

We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:

• Violent threats or language directed against another person.

• Discriminatory jokes and language.

• Posting sexually explicit or violent material.

When we disagree, try to understand why.

Disagreements, both social and technical, happen when people get passionate about what they are doing. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of open smart grid platform comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.

This Code of Conduct is based on the Django Code of Conduct

With the open smart grid platform we intend to have the right balance between a benevolent Dictator and a Formal Meritocracy in order to have a balanced decision-making process and to prevent unwanted dictators and everlasting discussions. The basic principle is that decisions are based on consensus. If this decision making process takes too long or a decision is required, the community council has the authority to make a decision. Grid eXchange Fabric complies with the LF Energy governance

The governance and rules should be respected.

Community council / Technical Steering Committee

The community council consists of 5 members and has the authority to make decisions on all community related subjects.

The community council is responsible for:

• General ambitions, objectives and goals

• Principles and understandings

• Governance and consultation bodies

When the community grows, members of the community council can be elected. If the situation demands or requires it, the community council has the ability to establish sub councils for a specific subject, area of domain.

The community council consist of the following members:

• - Lead Architect - Chairman

• - Product owner GXF & LF Energy TAC member for GXF

• - Lead Architect

If you would like to join the community council, please contact us! Mention @OSGP/communitycouncil in an github issue. The (online) community council meetings will happen when needed.

Maintainers

Maintainers are responsible for maintaining parts of the code-base. Maintainers have the following responsibilities

• Coordinate development activity

• Make sure code/documentation reviews are being done

• Coordinate pull-requests

In case of long discussions or arguments, maintainers or other can request a community council decision.

Current maintainers:

• GXF Platform and smart lighting domain:

• GXF Platform and Smart metering domain:

• GXF Architecture & documentation:

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.

Documentation Publication

This documentation is available in multiple formats.

Web

PDF

• Click on Export as PDF on right side of gitbook

Contributing to documentation

The documentation is build using GitBook software from Markdown files in the .

We encourage you to participate in improving the documentation. From corrected typos to new sections, every commit is appreciated. You can access the source files by clicking the "Fix this page"-button in the GitBook or by selecting the relevant Markdown-file in the documentation. You can commit your changes by sending a pull request.

1. Fork the repo, do work in a feature branch.

2. Issue a pull request.

3. Make sure the automated test suite succeeds. They will show-up in the pull request.

Some information on GitBook and using Markdown can be found , more elaborate information on GitHub-flavored Markdown is found . If you like to upload illustration, you can use git or

If you are completely new to this and you need help to get started, file an issue in the documentation repository.

Chapters in the documentation

It may be obvious to you already from the index, however, here is an overview on what documentation goes in which chapter.

• Chapter 1 consist of an open smart grid platform introduction and architecture for potential users, architects and developers. The open smart grid platform website is used for basic product information.

• Chapter 2 contains the general userguide for open smart grid platform users

• Chapter 3 contains community related topics

Versioning within the documentation

We have chosen to work with GitBook since it allows us to make different versions of documentation for each release. This is done by branching the files in the documentation repository. The master branch is used for releases only. The development branch is our main and current branch. If you like to improve the documentation, start a feature branch with your changes and send a pull request to the development branch.

Guidelines for new documentation

• The master branch is only used by major open smart grid platform releases

• Don't commit directly to the development branch, please do a pull request.

• We use the American spelling

Documentation inspiration

Inspiration on how to write good documentation can be found here: .

Thank you for contributing to the Open Smart Grid Platform. Please keep the following in mind before submitting code.

Guidelines

Before code is merged it needs to comply with a number of guidelines: 1. Code should be as complete as possible (preferably no placeholders, TODO's or FIXME's) 2. Right formatting; code should follow the Coding Conventions (see 3.1.2) 3. Fixed/added unit tests where applicable 4. Javadocs added where applicable 5. Accepting pull-requests with SonarQube reports "Blocker" and "Critical" are not allowed 6. Comply with International open standards where possible (e.g. IEC standards)

Contributor License Agreement

We ask each of our contributors to sign our contributor license agreement (CLA). This has advantages for both parties, it gives you the assurance that your contribution will remain available under the Apache 2.0 license. Meanwhile, you give your code in license to us, so we can add your code to the open smart grid platform. And we know your contribution is entirely your work, so we don't get in trouble with legal issues. Please read the CLA text carefully.

Submitting code

To submit changes to the open smart grid platform branches: 1. Create a fork of the open smart grid platform repo you will be working in 2. Make and commit your changes to your fork 3. Create a pull request to merge the changes into the right branch (see 4.1.4 for the branching strategy) If the changes fix a bug, mention the issue number in the commit message or pull request message (example: fixes 101, solved 87). If no ticket exists, create one beforehand. Afterwards, please update the relevant documentation in this GitBook.

Open Source Branching Strategy

The open smart grid platform's main branch is master. All major releases are tagged in this branch. Development is done in the development and feature branches. We use the GitFlow branching strategy. Find more information on this strategy here:

The GitFlow workflow is someone complicated, but it has the advantage that it gives a clear overview of all previous releases and current development and thus helps to collaborate more efficiently. Please follow this strategy in your commits.

Pull requests: review process

Anyone can send in a pull request. Assign a maintainer or other developer with knowledge on this topic to accept/evaluate your pull request. You can view the SonarCube test results at () and the Jenkins continuous integration results at ()

If your code is a useful contribution and meets our quality standards (see section 3.1), it will be added to the open smart grid platform! Developers are in charge of judging this. Don't forget to update the documentation as well.