Contributing to Substra

:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:

The following is a set of guidelines for contributing to the Substra framework, which is hosted on the Substra Foundation Organization on GitHub. These are mostly guidelines, not rules. Use your best judgment and feel free to propose changes to this document in a pull request.


This amazing piece of software has been developed and open sourced by Owkin and its terrific software engineers. The repositories are now maintained by Substra Foundation and its community. Besides, Substra is really excited to welcome new members, feedbacks and contributions, so please, feel free to get in touch with us!

Code of Conduct

This project and everyone involved is governed by the Code of Conduct defined here. By participating, you are expected to uphold this code. Please report unacceptable behavior to

I don’t want to read this whole thing I just have a question!

What should I know before I get started?

It might be useful to have a look at the documentation!

The components of Substra

Substra is made of several open source components listed below. When you initially consider contributing to Substra, you may be unsure of the component that implements the functionality you want to change or report a bug for. The table below should help you with that.

Component Goal
substra Documentation, CLI and Python SDK to interact with a Substra node.
substra-tools Toolkit to design assets to be registered to Substra.
substra-frontend Frontend to visualize the state of the assets registered to a Substra channel.
substra-ui UI component for the frontend.
substra-backend Backend of a Substra node.
substra-chaincode Smart contracts responsible for the decentralized orchestration.
hlf-k8s Tools to deploy a Hyperledger Fabric network on kubernetes.
substra-tests Tests for the framework Substra.

How Can I Contribute?

Improving the documentation

The documentation can be found here. We believe documentation is key to a great project and that it should be as alive as our project, so please, do not hesitate to submit any feedback or PR to improve it!

Reporting Bugs

This section guides you through submitting a bug report for Substra. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:.

Before creating bug reports, please check this list as you might find out that you don’t need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the required information will help us resolve issues faster.

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.

Before Submitting A Bug Report

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. After you’ve determined which repository your bug is related to, create an issue on that repository. This template should guide you to submit a good bug report.

If you really don’t know which repository your bug is related to, submit an issue here.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for Substra, ranging from minor improvements for already existing functionality to completely new features. Following these guidelines will help maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:.

Before creating enhancement suggestions, please check this list as you might find out that you don’t need to create a new one. When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including all the steps that you imagine you would take if the feature already existed.

You can also come chat with us on Slack in order to engage the community in discussing your suggestion.

Before Submitting An Enhancement Suggestion

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. After you’ve determined which repository your enhancement suggestion is related to, create an issue on that repository. The template should guide you to submit a good enhancement suggestion.

If you don’t know which repository your suggestion is related to, submit an issue to here.

Your First Code Contribution

Not sure where to start?

You can have a look through these [Beginner] and [Help-wanted] flagged issues:

  • [Beginner] issues are issues that should only require a few lines of code, and a test or two.

  • [Help wanted] issues are issues that should be a bit more involved than beginner issues.

Both issues lists are sorted by total number of comments. While not perfect, the number of comments is a reasonable proxy for impact a given change will have.

Note: translation or reformulation can be good entry points on the project.

Local development

Substra can be developed locally. For instructions on how to do this, see this page which is part of the Substra Documentation.

Pull Requests

Hint: Before starting a Pull Request, opening an issue is a good way to reach the team involved (most likely the reviewers of your submission) and discuss your proposition!

The process described here has several goals:

  • Maintain the quality of Substra

  • Fix problems that are important to users

  • Engage the community in working toward the best possible Substra

  • Enable a sustainable system for Substra’s maintainers to review contributions

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

  1. Follow the coding guidelines

  2. After submitting your pull request, verify that all status checks are passing.

Pull Requests Status

For example, in this caption of the open Pull Requests on the main Substra repository, we can see that:

  • The Pull Request called “Type hints” is not passing tests

  • Others are passing

What if the status checks are failing?

If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.

While the prerequisites above must be satisfied prior to having your pull request reviewed, reviewer(s) may ask you to complete additional design work, tests, or other changes before your submission can be ultimately accepted.

Note: In order to ease the process, please consider creating a specific branch with an explicit name pointing towards the masterbranch. You might even fork the whole repository and then open a Pull Request using compare accross forks. Please refer to Github documentation for further information.

Code review

Reviewing code is a crucial component of the development of the project. We strongly encourage anyone to start reviewing code of other developers as it often is highly educational for everyone involved.

Review checklist

Please make sure you went through this checklist:

  • Does this code read like prose?

  • Do the methods do what their name claims they will do? Same for classes?

  • Is the code as modular as possible?

  • Can I get an understanding of the desired behavior just by doing quick scans through unit and acceptance tests?

  • Does the understanding of the desired behavior match the requirements/stories for this work?

  • If there is a small doubt on the fact that acceptance tests might not be enough? Have I tested that it works?

  • Is this code introducing any new dependencies between classes/components/modules and, if so, is it necessary to do that?

  • Is this code idiomatic, taking full advantage of the language, frameworks and tools we use?

  • Is anything here a re-implementation of existing functionality the developer may not be aware of?

Review best practices

Please make sure to be as constructive as possible. This article summarizes unhelpful and helpful behaviors when doing a code review: Unlearning toxic behaviors in a code review culture:

Unhelpful behavior
  • Don’t make claims unless you can cite documentation, formalized guidelines and coding examples to back those claims up.

Instead of saying:

This component should be stateless.

Provide some context behind the recommendation:

Since this component doesn’t have any lifecycle methods or state, it could be made a stateless functional component. This will improve performance and readability. Here is some documentation.

  • Don’t ask judgmental questions.

Avoid asking questions like:

Why didn’t you just do ___ here?

Oftentimes, these judgmental questions are just veiled demands. Instead, provide a recommendation (with documentation and citations) and leave out harsh words.

You can do ___ which has the benefit of ___.

  • Avoid being sarcastic.


Did you even test this code before you checked it in?


This breaks when you enter a negative number. Can you please address this case?

  • Don’t ask engineers to solve problems they didn’t cause “while they are at it”.

If the code solves the issue/ticket the dev was working on and doesn’t introduce any new issues to the codebase, give the pull request a “thumbs up” and then create a ticket to clean up the existing bad code.

  • Don’t ghost people.

Helpful Code Review Practices
  • Use questions or recommendations to drive dialog

  • Collaborate, don’t back-seat drive

  • Respond to every comment

  • Know when to take a discussion offline

The kinds of problems that take hours and tons of comments can usually be resolved in a few minutes of productive talk. — Tidy Java

  • Use opportunities to teach, and don’t show off

Before choosing to participate in a code review, ask yourself:

Is your comment helping the other developer learn or are you nitpicking to participate?

  • Don’t show surprise. Don’t make people feel bad that they “should already have known” this piece of information, cf. feigned surprise.

Coding guidelines

This section points to standard guides we try to follow in the Substra project.

Python Coding Guideline

  • Our libraries supports python 3.6 and newer

  • Our applications are written for python 3.6

The Substra project tries to closely follow the official Python guidelines detailed in PEP8. Please read it and follow it.

You can check your code using flake8.

In addition, please apply the following guidelines:

  • Line length up to 119 characters, contrary to the PEP8 guidelines. PEP8 recommends a 79 char limit, but we believe that sometimes it makes the code harder to read.

  • Use double quote " when a string contains single or double quote characters, however, use the other one to avoid backslashes in the string.

  • String formatting: use f-strings

  • Docstings: PEP-257 says that “The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions. However, it doesn’t specify any details of what this should look like. Fortunately, the Google python style guide provides a reasonable syntax for arguments and return values.

  • Avoid use of “we” in comments, e.g. “Loop over” rather than “We loop over”.

  • When contributing to existing projects - do not change the style.

Go Coding Guidelines

The Substra project tries to follow the following resources:

Third Party Library Usage

There are several advantages of using third party libraries:

  • Saving time

  • Not reinventing the iPhone

  • Using tested code

  • Using modular code

But there are also some disadvantages:

  • Dependencies

  • Lack of Support

  • Overuse

  • Security Issues

How to choose the right library?

To maximise advantages over disadvantages, please carefully consider the following questions:

  • Is this library going to be used for core features?

  • Is the library maintained?

    • Release frequency, number of issues, pull requests could be good indicators.

  • How popular is the library?

    • Ecosystem and community (stars on github, stackoverflow discussions, etc), you can also check fake stars on Github.

    • Blog posts.

    • Who use the library at scale?

  • How reliable is the author?

  • How well-written is the library?

    • The library meet common langage good practices.

    • The library have tests and is well documented.

  • Does the library meet your specific requirements?

  • Does the library have the correct license?

  • Is library Licence compatible with our project and licences policies?

  • Is there a security policy defined in the project?

How to check licence compatibility

The Substra project is license under a Apache 2.0 license. Libraries used in the project must thus be permissive licenses.

Additional Notes

Issue and Pull Request Labels

This section lists the labels we use to help us track and manage issues and pull requests. These labels are used across all Substra repositories.

GitHub search makes it easy to use labels for finding groups of issues or pull requests you’re interested in.

The labels are loosely grouped by their purpose, but it’s not required that every issue have a label from every group or that an issue can’t have more than one label from the same group.

Please open an issue with a Add_Label flag, define if you have suggestions for new labels, and if you notice some missing labels on some repositories, then please open an issue on that repository.

Type of Issue and Issue State

Label name :mag_right: Description
enhancement search Feature requests.
bug search Confirmed bugs or reports that are very likely to be bugs.
question search Questions more than bug reports or feature requests (e.g. how do I do X).
feedback search General feedback more than bug reports or feature requests.
help-wanted search The Atom core team would appreciate help from the community in resolving these issues.
beginner search Less complex issues which would be good first issues to work on for users who want to contribute to Atom.
more-information-needed search More information needs to be collected about these problems or feature requests (e.g. steps to reproduce).
needs-reproduction search Likely bugs, but haven't been reliably reproduced.
blocked search Issues blocked on other issues.
duplicate search Issues which are duplicates of other issues, i.e. they have been reported before.
wontfix search The Atom core team has decided not to fix these issues for now, either because they're working as intended or for some other reason.
invalid search Issues which aren't valid (e.g. user errors).
wrong-repo search Issues reported on the wrong repository.

Topic Categories

Label name :mag_right: Description
documentation search Related to any type of documentation.
security search Related to security.

Pull Request Labels

Label name :mag_right: Description
work-in-progress search Pull requests which are still being worked on, more changes will follow.
needs-review search Pull requests which need code review, and approval from maintainers or Atom core team.
under-review search Pull requests being reviewed by maintainers or Atom core team.
requires-changes search Pull requests which need to be updated based on review comments and then reviewed again.
needs-testing search Pull requests which need manual testing.

Security Policy

Please refer to this section if you want to submit any security related issue.