|
|
[[_TOC_]]
|
|
|
|
|
|
Our guidelines are based on the [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)
|
|
|
|
|
|
NOTE: Format guidelines are only enforced for commit messages to a protected branch or on a MR to a protected branch. But we reccomend doing your best to maintain this format at all times.
|
|
|
|
|
|
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 introduces breaking changes. Indicated in the commit body (see examples)
|
|
|
- **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|
|
|
|
| **docs** | Changes to accompanying documentation|
|
|
|
|
|
|
### OSC 1.x
|
|
|
| identifier | description |
|
|
|
|---|---|
|
|
|
| **model** | Domain model specification|
|
|
|
| **docs** | 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
|
|
|
```
|
|
|
|
|
|
## 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. |
|
|
\ No newline at end of file |