Semantic Versioning

Important

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Semantic Versioning 2.0.0

This project SHALL conform to Semantic Versioning 2.0.0, as described.

What is considered part of the Public API?

The described Public API in the context of this project SHALL consider:

• All .mustache template files
• All .java files generated by, or modified, by these .mustache template files
  • Identified by the license header in beginning of generated files
  • Including changes to functionality, behavior, documentation, and formatting
• Project metadata in pom.xml

Note

GitHub Issues and Pull Requests SHALL be labelled with a semantic version label (MAJOR, MINOR and PATCH) for:

• Any feat (Feature)
• Any bug (Bug Fix)

What is not considered part of the Public API?

The following SHALL NOT be considered part of the Public API:

• Project <properties>, <dependencies> and <build> properties in pom.xml
• Any and all other files (.yaml and .java)
  • java files located in /generated-sources
  • java files located in /src
  • yaml files located in /src
• The README
• Any and all files related to GitHub (GitHub Actions, GitHub Pages, GitHub Templates, etc.)

Note

GitHub Issues and Pull Requests SHALL NOT be labelled with a semantic version label (MAJOR, MINOR and PATCH) for:

• Any meta (Meta change)
• Any doc (Documentation change)
• Any test (Test change)
• Any dependencies (Dependency Update)
• Any github-pages (GitHub Pages change)

Exceptions & Limitations

• Retrieving .mustache template files

  • ✔️ Importing as a dependency (Maven, Gradle, etc.) SHALL be considered
  • ❌ Downloading directly from GitHub SHOULD NOT be considered

• Generating classes using .mustache files

  • ✔️ Using all the provided .mustache files as-is SHALL be considered
  • ❌ Using a subset of the provided .mustache files as-is SHALL NOT be considered

• Modifying .mustache template files

  • ✔️ Unmodified and unaltered files SHALL be considered
  • ❌ Modified and/or altered files SHALL NOT be considered

• OpenAPI Specification properties

  • ✔️ Using supported properties SHALL be considered
  • ❔ Using properties prior to adding support MAY be considered
  • ❌ Using unsupported properties SHALL NOT be considered

• openapi-generator Configuration properties

  • ✔️ Using supported properties SHALL be considered
  • ❔ Using properties prior to adding support MAY be considered
  • ❌ Using unsupported properties SHALL NOT be considered

Exact definitions for Semantic Versioning

MAJOR

When a breaking change is made to the Public API. A change SHALL be considered a breaking change, if any of the following are true:

• Removal of functionality and/or behavior
• Incompatible and/or non-backward compatible change to functionality and/or behavior
  • This SHALL also apply to changes that MAY be incompatible in less common, but expected, scenarios
• Any change requiring additional attention by users (Changes to licensing, etc.)

MINOR

When new functionality is added, in a backward compatible way. A change SHALL be considered a minor change, if:

• The change SHALL NOT fulfill any major change conditions
• The change SHOULD introduce new functionality and/or behavior

PATCH

When a bug within an existing functionality or behavior is fixed, in a backward compatible way. A change SHALL be considered a patch change, if:

• The change SHALL NOT fulfill any major change conditions
• The change SHALL NOT fulfill any minor change conditions
• The change MAY fix a bug to existing functionality and/or behavior
• The change MAY be non-functional, and affects code formatting and/or documentation