- Types
- Scopes
- Subject
- Body
- Footer
- Examples
- FAQ
- What do I do if the commit conforms to more than one of the commit types?
- How does this relate to SemVer?
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.