Knowledge Base Administration Guide

Commit changelists — Advanced model flow

Note: this is an optional flow.

For advanced flow, Simscope can automatically link commits to a parent integrate. This lets users figure out which regression is the first to contain their checkin.

For example, if we assume this timeline:

integrate2
└── commit4

integrate1
├── commit3
├── commit2
└── commit1

Where integrate1 and integrate2 are merge commits into a master branch, Simscope can link the merged commits automatically.

  • In this example, searching for commit1, commit2, or commit3, Simscope will automatically link them to the integrate integrate1.

Integrate model changelist format

Simscope integrates are formatted using a Tab-Separated-Value (TSV) file.

These get imported during a regression import, linked inside the Regression JSON:

    "changelist_path": "/path/to/mychangelist.tsv",

TSV fields

FieldDescriptionExampleRequired
idThe unique commit identifier6141bbb86c70f8a0b9d197✅
parentsParent commit (or multiple for a merge)504a5c051d8325479d498optional
author_emailEmail address of the commit authorfoo@bar.com✅
dateTimestamp (RFC3339) of the commit2018-10-12T08:34:31-07:00✅
messageCommit messageHey, this fixed bug 1000optional
filestatslist of files in the commit...optional

Sample TSV output

This is a minimal TSV sample containing 4 changelists (with just commit ID, author email, and date fields):

id	author_email	date
6141bbb86c70f8a0b9d1971cf50e79e694e0a050	github@frew.co	2018-10-12T08:34:31-07:00
901648c87902174f774fac311d7f176f8647bdaa	andy@balholm.com	2018-02-20T10:43:36-08:00
349dd0209470eabd9514242c688c403c0926d266	andy@balholm.com	2016-12-24T06:14:13-08:00
7fb769b0e2399d2749ad9c9844e5447e29db6438	ryan.a.cox@gmail.com	2016-12-23T17:29:03-08:00
  • Note the tab character (ie '\t') between each field

Here is a full TSV file containing 4 changelists (showing all available TSV fields):

id	parents	author_email	date	message	filestats
6141bbb86c70f8a0b9d1971cf50e79e694e0a050	901648c87902174f774fac311d7f176f8647bdaa	github@frew.co	2018-10-12T08:34:31-07:00	Add link to Godoc	"M      README.md"
901648c87902174f774fac311d7f176f8647bdaa	349dd0209470eabd9514242c688c403c0926d266	andy@balholm.com    2018-02-20T10:43:36-08:00	Add go.mod file for vgo.	"A      go.mod"
349dd0209470eabd9514242c688c403c0926d266	7fb769b0e2399d2749ad9c9844e5447e29db6438 2fe1a003673e5eae31dd39feaec3bc76c34543ec   andy@balholm.com	2016-12-24T06:14:13-08:00	Merge branch 'lint' of https://github.com/ryancox/cascadia
7fb769b0e2399d2749ad9c9844e5447e29db6438	da751972c7ffb0c5792de2b95cb92f28ebed00fa	ryan.a.cox@gmail.com	2016-12-23T17:29:03-08:00	implement :root element "M      parser.go"

Generating changelist TSV from Git

Simscope comes with a git plugin, which will convert a git history into the TSV format, for imports.

# Usage
$ cd GIT-WORKSPACE
$ simscope-changelist-git.py [GIT-ARGUMENTS]

Example usage:

# Example (grab all commits between 6141b and 2fe1a)
$ simscope-changelist-git.py 6141b...2fe1a > changelists.tsv

To use this script in your workflow, call it before importing your integrate regression into Simscope:

  1. Call simscope-changelist-git.py to generate regression-abc.tsv
  2. Create regression-abc.json, and link to regression-abc.tsv
  3. Import regression-abc.json into Simscope