Developer usages and tools

Date: 06/08/2021

Version: 0.1

Introduction

The purpose of this guide is to explicit the coding rules and conventions used for this project and explain the use of some of our tools.

This guide is dedicated to the internals or externals (collaborators) developers.

Some aspects of this guide may change in the future (e.g. the code organisation), stay alert for such changes.

Code

Code organisation

The code is contained in one git repository with 3 functional parts:

  • network: a top layer which contains network layers (http server, message server) and a set of scripts to start the services and the components of fedbiomed.

  • node: the library and tools to run on each node

  • researcher: the library and tools to run on researcher's side

Coding environment

Except for some bash tools and scripts, the python language is used for main parts of the code.

conda is used to ease the installation of python and the necessary python modules.

Coding style

We try to stick as close as possible to python coding style as described here

Coding style validation

We do not enforce coding style validation at each commit. In the future, we may implement some of the tools described here

Gitflow paradigm

The gitflow paradigm must be followed when creating new developement branches and for code release ( see here or here)

Gitlab usage

All code is published on the Inria's gitlab instance: https://gitlab.inria.fr

Main branch configuration

As we use the gitflow paradigm, the master branch of each repository only contains new releases.

The master branch is protected and only writable to users with maintainer role.

Inria is currently responsible of the process of providing new releases.

External accounts

Collaborators outside Inria are provided with a gitlab external account.

This account is personnal and cannot be shared with someone else.

There is a restriction on external accounts on our gitlab server: external accounts are not authorized to create new projets. As a consequence, an external user is also not authorized to fork a project.

For this reason, external account do not have the maintainer role and all external contributions must be validated by an Inria developer, after a proper merge request.

Merge request

To incorporate new features into the develop branch, the development must be done in a feature branch (refer to gitflow paradigm), which is merged via a gitlab merge request to the develop branch.

A merge request is usually associated with a gitlab issue, which must be closed after the merge is done. The feature branch is also deleted after the merge.

The merge request is currently validated by an Inria developer after a validation process, conforming to the definition of done (DoD) document.

Organization

We work as an agile team inspiring from Scrum and loosely implementing it (eg no full product backlog maintained yet).

Work is organized in sprints (or simply "iterations" eg during summer)

Product backlog

Product backlog is a Scrum artifact

Product backlog entries are issues (see below). Each product backlog entry can contain a functional requirement, a user story, a task, etc.

Sprint backlog

Sprint backlog is a Scrum artifact

During a sprint, a gitlab milestone is created for each sprint backlog item.

Sprint backlog milestones can be refined during the sprint, and one or more issues (tasks, functional requirements) are created and assigned to them.

Issues

Gitlab issues are used: - for sprint backlog milestone subdivision (see above) - for proposals by developers or end user (currently, only users with a gitlab account can report in an issue) - for product backlog entries

Issues should have a significant title, description of the problem/task and when useful info on the main actions taken.

Milestone issues

Milestone issues from the sprint backlog shall be only modified by the developers' team for implementing the sprint backlog and its advancement.

A developer taking the lead on an issue should assign {him,her}self the issue (Assignee), update the issue labels with status tags (Todo, Doing, In review, Done, Postponed) and type tags (see above). When the DoD is met, the issue is labeled as Done and closed.

Proposal issues

Proposal issues can be submitted by any developer or end user with enough gitlab access (currently, it requires a gitlab account).

The submitter should tag the issue with appropriate type tags : bug, feature, improvement. The issue can be considered by the developers' team (for including in the sprint backlog, quick solving).

If the issue is tagged with proposal, it will also be considerered by the product owner for including to the product backlog.

Product backlog issues

Product backlog issues are created, modified, removed by the product owner only or with explicit validation of the product owner.

They are tagged with backlog.

Product backlog entries are often removed when added to sprint backlog (or after being completed in the sprint).

Issues and milestones should be easily linkable with their corresponding code branches (and vice versa). We currently don't have a standard for that, but using explicit branch naming and/or comment in issues is a good practice.

Other tools

  • project Discord chat server
  • mail lists : discussion list ; development events list (push, commit)
  • project file repository (Mybox Fed-BioMed-tech)
  • CI server https://ci.inria.fr/fedbiomed/

User documentation:

  • https://fedbiomed.gitlabpages.inria.fr
  • examples notebooks in fedbiomed/notebooks

Developer documentation:

  • current version in https://fedbiomed.gitlabpages.inria.fr
  • WIP and archive documents in project file repository