Skip to content

GitLab

W
wiki

Simulation Wiki now available - includes a first sketch of workflow and project guidelines. Get in touch if you have any feedback!
https://code.asam.net/simulation/wiki/-/wikis/home

Commit Guidelines

Last edited by Benjamin Engel
Page history

In addition to requiring a sign off message for open source projects we make use of the Conventional Commits Specification

NOTE: Format guidelines for conventional commits are only enforced for commit messages to a protected branch or on a MR to a protected branch. But we recommend doing your best to maintain this format at all times. Please try to be short and informative in the description. This will help other to easier understand the commit. The description should be max. 50 characters.

TIP: Commit often! Do not put multiple changes across sections into one commit. Splitting them up into individual commits will make review and merging easier.

The commit message should be structured as follows

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

  • Development changes
    • fix: Patches a bug in the standard and directly corresponds to a PATCH release
    • feat: Describes a new feature in a backwards compatible way and corresponds to a MINOR release
    • Breaking Change: This indicates MAJOR changes that introduce breaking changes. Indicated in the commit body (see examples)
fix(docs): Remove link to TrafficSignals

Fixes #249
  • style commits that do not affect the meaning (white-space, formatting, missing semi-colons, etc)
  • build commits that affect build components like build tooling, ci pipeline, dependencies, project version, ...

Scopes

The scope provides additional contextual information.

  • Allowed Scopes depends on the specific project

OSI

identifier description
code OSI specification code changes
inlinedocs OSI specification code changes
docs Changes to accompanying documentation

OSC 1.x

identifier description
model Domain model specification
modeldocs HTML documentation on the model
modelingguidelines Modeling guidelines for the UML model
examples Accompanying examples
userguide Accompanying user guide

OSC 2.0

identifier description
lrm Language reference manual
model Domain model specification
docs Accompanying documentation

OpenXOntology

identifier description
ontology Changes targeting the ontology implementation
documentation Changes targeting the specification documents

Subject

The subject contains a succinct description of the change.

  • Use the imperative, present tense: "change" not "changed" nor "changes"
  • Don't capitalize the first letter
  • No period (.) at the end

Body

The body should include the motivation for the change and contrast this with previous behavior.

  • Is an optional part of the format
  • Use the imperative, present tense: "change" not "changed" nor "changes"
  • This is the place to mention issue identifiers and their relations

Footer

The footer should contain any information about Breaking Changes and is also the place to reference Issues that this commit refers to.

  • Is an optional part of the format
  • optionally reference an issue by its id and gitlab/github will add links - (#<issue_id>, e.g. #14)
  • Breaking Changes should start with the word BREAKING CHANGES: followed by space or two newlines. The rest of the commit message is then used for this.

Examples

feat(lrm): Add a section on basic types
feat(model): Prevent empty StopTriggers 

refers to #23
BREAKING CHANGES: StopTrigger can no longer be empty
fix(docs): Clarify example 10
There was an ambiguity in the example that was not clear. 
Clarified the parameters being used.
build: Change CI structure
style: Remove empty line

Signed-off-by: Ben Engel <ben@email.address>

FAQ

What do I do if the commit conforms to more than one of the commit types?

Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs.

How does this relate to SemVer?

ASAM labels adhere to the Semantic Versioning standard. Commit types are mapped as follows:

fix type commits should be translated to PATCH releases. feat type commits should be translated to MINOR releases. Commits with BREAKING CHANGE in the commits, regardless of type, should be translated to MAJOR releases.