A cross indicating indicating a button to close the menu

Contributing to the project

This section describes the basic interactions within the community from the perspective of a future contributor to the project.

  • First steps
  • Easiest way to start
  • Raise an issue
  • Submit changes for approval
  • Suggest a feature

First steps

Contact working groups

In order to engage with the community, get in touch with any of the working groups that lead the project.

Read code of conduct

Before going ahead, please read the code of conduct that should govern your future activities and behaviour as a contributor within the project. These are not but well-known common sense and accepted practices across the open source ecosystem which you must abide by.

Easiest way to start

Why don’t you help us to fix an issue? We humbly publicize in our GitHub repo areas where we most looking for contributor help are. Search for the labels good first issue (for first time contributors) and / or help wanted (if you dare to start with a more complex matter).

Have a look at this README file to learn about the code and to set-up your development environment.
Finally, if you are interested to know about the pull request mechanism see here.

Raise an issue

Have you tried the tool and unluckily found an issue in it? Well, yeah, we are not perfect, you know. Why don’t you file a bug in our repo?

We like to know about our bugs, but especially when they concisely detail the steps to reproduce them and version of the project you were using. Even better if you include a stacktrace or screenshot where applicable.

Submit changes for approval

These are the steps to submit your proposed change:

  • Fork the repository
  • Make the fix
  • Submit a pull request

Please refer to this github help page if you need help with submitting pull request from your fork.
In order to accept your pull request submission, the following activities have to take place:

  • Code review
  • Code approval

Pull request review

Upon pull request submission the specific code owners will be assigned with the review of the change. Code owners, who must be a member of the community with role member, approver or lead, will take the responsibility to review the pull request.

The review will be performed in terms of quality and rightness of the code change. The reviewer will have the option to approve, request a change or simply comment without approval. In any case the feedback must be always helpful and strictly following the code of conduct, especially when a PR is blocked.

Each pull request needs to be tested by running the code through the Continuous Integration (CI) system. Given that collaborators do not have permissions to run automated tests, the reviewer can start a CI run on your behalf. Only when all tests are passed, the review can be approved.

Approving a change

Only contributors with role approver or lead are authorized to approve code changes. No member is allowed to approve their own PR’s though.

The pull request will need to have at least one “approved” review and be free of “request changes” from a reviewer. In these conditions, and provided that the change covers all aspects expected from the wider perspective of the project, besides quality and rightness, the approver will merge the change into the repository.

Suggest a feature

A feature is a complex implementation which generally is addressed to fix a problem in the project. In order to suggest a feature, the following steps should be followed:

  • Problem statement
  • Design proposal
  • Proposal review
  • Split feature
  • Delivery

Problem statement

Raise an issue that describes and explains the problem to be addressed, in case it doesn’t exist yet. The issue should be labelled adequately to bring the attention of the working group lead where it is impacting who will manage its prioritisation.

Design proposal

Given that a feature is considered a non-trivial issue, a design will be required. The design document should be uploaded to the working group team drive.

Proposal review

The proposal will be discussed during the working group meeting with the objective of being approved. While working group leads are responsible for granting the final approval to the design. When the design spans several working groups, those working group leads should engage to split or decide on a joint approach to the design.

Split feature

Decomposition of the feature into pull requests of a manageable size is key to success in the feature implementation.

Delivery

The generated items out of the feature decomposition will be planned into the project milestones and delivered by the working group members.