Jump to content

Wikimedia Cloud Services team/EnhancementProposals/Decision record T373072 to strictly enforce semantic versioning rules for toolforge services APIs or not

From Wikitech

Origin task: phab:T373072

Date of the decision: 2024-09-26

No decision meeting was needed, agreement reached in the task.

Decision taken

Option 2 was chosen, to manually enforce semantic versioning.

Rationale

  • It is the least labor-intensive option.
  • There is little ROI in going with the more labor-intensive options.
  • It forces us to think about the impact of our code changes, and to discuss it during code review.

Semantic Versioning Principle Summary

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backward compatible manner
  • PATCH version when you make backward compatible bug fixes

Problem

Now that the consolidated Toolforge services API is being exposed to the public, users will expect the API version information to be consistent and have proper semantic meaning. Though we never really had a decision request for it (can't remember if we did), we made the tacit decision to use semantic versioning or what appears to be it (at least to our users) for the individual services' APIs and consolidate the versions of the individual services into a single version following rules that still obey semantic versioning principles, before showing this information to our users. The problem is that right now we only have very basic validation rules for the individual APIs, rules that are not true to semantic versioning principles, so what appears to be semantic versioning to the API users may not really be that.

For example right now if you make a breaking change to `jobs-api` openapi schema and only bump the patch version i.e `1.0.0` ----> `1.0.1`, the current validation rules we have will not complain.

Decision Request Goal

  • Decide on how to ensure that the version number of our APIs reflect the changes made to the API schemas, according to semantic versioning rules.

Constraints and risks

  • The consolidated API is currently public which means we have limited time to make up our minds on this.

Decision record

Option 2 choosen. https://wikitech.wikimedia.org/wiki/Wikimedia_Cloud_Services_team/EnhancementProposals/Decision_record_T373072_to_strictly_enforce_semantic_versioning_rules_for_toolforge_services_APIs_or_not

Options

Option 1

Do nothing

Pros:

  • we won't have to do the work

Cons:

  • the problem is still there


Option 2

manually enforcing semantic versioning. this means we official have it on record that we are doing semantic versioning but leave it at the discretion of the person submitting the patch and the reviewer to decide what that means.

Pros:

  • Better than Option 1
  • We can start this now

Cons:

  • Pron to error


Option 3

automatically enforce semantic versioning using our own custom algorithm

Pros:

  • semantic versioning automatically enforced

Cons:

  • Might take longer to setup compared to other alternatives
  • unanticipated edge cases?


Option 4

automatically enforce semantic versioning using third-party solutions

Pros:

  • semantic versioning automatically enforced
  • potentially faster than Option 3 (at the very least most edge cases should be handled)

Cons:

  • more limited compared to Option 3. So far I only know of oasdiff which only has command-line and go packages (maybe those are enough, maybe not)
  • dependency?
Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Wikimedia_Cloud_Services_team/EnhancementProposals/Decision_record_T373072_to_strictly_enforce_semantic_versioning_rules_for_toolforge_services_APIs_or_not&oldid=2232292"