Skip to content

Process Documentation

Jump to bottom
Michael Jastram edited this page Sep 17, 2015 · 15 revisions

In this chapter, the underlying processes, used by WP3 and WP4, are documented.

Table of Contents

Conventions

Requirements Identifiers from Subset-26

TODO Moritz will communicate the naming convention of his tool.

WP3 Modeling

Document Implementation Coverage

The requirements from Subset-26++ have to be linked with the Scade Suite Model Artifacts ("realization traces"), to identify which requirement is implemented where. (implementation coverage)

WP3 wants to create reference links that are not implementation links.

As a modeler, I want to see the requirement(s) associated with a model element, so that I understand what the model is supposed to do.

WP4 V&V

Continuous Integration Process

For the modeling and V&V teams it is important that the modeling repository contains only artifacts that compile without errors (at a minimum). Due to the nature of the tools used (Scade Suite requiring expensive licenses), it is not possible to perform build automation within openETCS.

Therefore, a lightweight, manual process is needed to ensure error-freeness in the repository. The following process is inspired by gitFlow.

One requirement is to impose as little inconveniences to the team as possible. They are currently working on the master branch. We will keep it that way, even though gitFlow works differently. In fact, the main change can be seen as a change in naming convention: (gitFlow)develop becomes (openETCS) master, and (gitFlow) master becomes (openETCS) stable.

High-Level process description

  1. Modelers work on master
  2. Optionally, they may use features branches that are merged into master upon completion
  3. On regular intervals (or as needed), the build master will merge the changes from master into stable.
  4. Once stable is stabilized, the adjustments are merged back into master.
  5. The stable model is tagged

Prerequisites

This is not a git tutorial. We provide command line commands for your convenience, but won't cover their meaning in Detail.

Detailed process

The following image depicts the process. There are two mandatory branches, master and stable. Modelers can also create an arbitrary number of feature branches. The rule of thumb is:

Producers of content should work on the master branch, which should contain the latest greatest, but may be broken.

Consumers of content should use the stable branch, which is guaranteed to work, but may be outdated.

This process is kept concise on purpose. If you need more background, or if you need a more exotic functionality, please consult the gitFlow documentation.

Consumer Workflow

A consumer is interested in always working on a stable model, even if it is slightly outdated. To ensure that a consumer does not accidentally changes the branch, the model shall be used only read-only, by checking it out anonymously, as follows:

Initial Consumer Checkout 

 git clone -b stable https://github.com/openETCS/modeling.git

To update the model with a new version, use the following command in the model folder:

Update the stable model 

 git pull

Note: Nothing is stopping you from modifying the model, you just cannot update the repository. If you modify the model (by accident or purpose), you may want to check out a fresh version, as you may get merge conflicts otherwise.

Producer Workflow

A producer is actively working on the model. All changes should be done on the master branch, no exceptions!

As master is checked out by default, producers can clone without specifying a branch. There are approaches to cloning the repository:

Committers of the openETCS modeling repository can check out the repository using their gitHub identity. This allows them to push changes directly to the repository.

Non-Committers must check out the repository read-only. To push changes, they must issue a pull request.

Check out the development repository as a committer 

 git clone git@github.com:openETCS/modeling.git

You can work, commit and push changes on this branch as you see fit, but please, don't break it on purpose. :-)

Feature Branches

It is recommended to work on a separate branch, if a modification is expected to take more than a day.

Note that it's (almost) impossible to merge binary files. Therefore, use feature branches only for text files.

Buildmaster Workflow

The build master is responsible for updating the stable branch such that it contains a model with certain quality criteria.

It is up to the modeling teams to define the quality criteria and is explicitly not listed here. At a minimum, stable should not contain compile errors.

The buildmaster performs the following steps:

Create Release Branch

The buildmaster creates a new release branch:

Create Release Branch 

 git checkout -b release

QA on Release Branch

Now the buildmaster can ensure that the release branch has the required quality, without affecting other users.

This is also the right time to bump up version numbers, if desired.

Releasing to stable

Once everything is as desired, the release branch can be merged into stable:

Merge into stable 

 git checkout stable
 git merge --no-ff release

It is recommended to create a tag (enter the correct version, of course):

Tag the release 

 git tag -a v.2

Last, the changes the buildmaster performed need to be merged back into the master branch:

Update master 

 git checkout master
 git merge --no-ff release

At this point, the release branch is not needed any more and can be deleted:

Delete Release 

 git branch -d release
Clone this wiki locally