12 Questions to Demystify Semantic Versioning

This article is a translated version of my original post on Qiita. Original (Japanese): https://qiita.com/segur/items/8ab94f4f99f26d31999c

Introduction

I organized a seminar on semantic versioning for beginners using package management tools. The quiz format we used was well-received, so I am sharing the materials from that session.

By answering these questions, you will gain a good understanding of how semantic versioning works!

Give it a try!

What is Semantic Versioning?

This is one way to assign version numbers, often abbreviated as SemVer.

npm, a package management tool for Node.js, is a well-known example of using semantic versioning. Learn more here.

For detailed specifications of semantic versioning, please refer to the following page: https://semver.org/lang/en/

In this article, we will refer to the page mentioned above as the "specifications."

Semantic Versioning Quiz

Question 1: Which of the following version formats is correct according to semantic versioning?

Answer and Explanation
Correct answer: **0.11.0** According to the specifications: > A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For example: 1.9.0 -> 1.10.0 -> 1.11.0. Explanation for each choice: - [ ] 0.01.0: Incorrect because leading zeroes are not allowed. - [ ] 0.1.3.1: Incorrect because the format must be X.Y.Z. - [ ] 1-1-0: Incorrect because the format must be X.Y.Z. - [ ] 1.2.a: Incorrect because X, Y, and Z must be non-negative integers. - [ ] 3,9,2: Incorrect because the format must be X.Y.Z. - [ ] 2.-1.3: Incorrect because X, Y, and Z must be non-negative integers. - [x] 0.11.0: Correct.

Question 2: A bug was found in version 1.1.9! After fixing the bug, what will the version number be?

Answer and Explanation
Correct answer: **1.1.10** According to the specifications: > Patch version Z (x.y.Z | x > 0) MUST be incremented if only backward-compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. Explanation for each choice: - [ ] 1.1.9.1: Incorrect because the format must be X.Y.Z. - [x] 1.1.10: Correct as the patch is incremented for a bug fix. - [ ] 1.2.0: Incorrect since no new functionality was added.

Question 3: A new path (new feature) was added to the Web API in version 1.2.5! The existing features have not changed. What will the version number be?

Answer and Explanation
Correct answer: **1.3.0** According to the specifications: > Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backward-compatible functionality is introduced to the public API. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented. Explanation for each choice: - [ ] 1.2.5.1: Incorrect because the format must be X.Y.Z. - [ ] 1.2.6: Incorrect because a new feature was added, not a bug fix. - [x] 1.3.0: Correct as new functionality means incrementing the minor version. - [ ] 1.3.5: Incorrect because patch version must be reset when the minor is incremented. - [ ] 2.0.0: Incorrect as the change is backward-compatible.

Question 4: At the early stage of development, what is the safest initial version number? (It's also a matter of convention)

Answer and Explanation
Correct answer: **0.1.0** According to the specifications: > In the early stages of development, version numbers can safely start at 0.1.0 and increment minor version for each subsequent release. Explanation for each choice: - [ ] 0.0.0: There's no harm here, but the specifications suggest starting at 0.1.0. - [ ] 0.0.1: There's no harm here, but the specifications suggest starting at 0.1.0. - [x] 0.1.0: Correct as per the specifications. - [ ] 1.0.0: Incorrect since the software is not yet public.

Question 5: After refactoring version 1.2.7, the processing speed doubled! The API specification hasn't changed. What will the version number be?

Answer and Explanation
Correct answer: **1.2.7** or **1.3.0** According to the specifications: > Minor version Y (x.Y.z | x > 0) MAY be incremented if significant new functionality or improvements are added internally, even with compatible API. Explanation for each choice: - [x] Remain 1.2.7: Correct; no external change. - [ ] 1.2.7.1: Incorrect because the format must be X.Y.Z. - [ ] 1.2.8: Incorrect as there's no bug fix. - [x] 1.3.0: Correct if internal changes warrant a version increment. - [ ] 2.0.0: Incorrect since backward compatibility is maintained.

Question 6: You're developing both a mobile app and a Web API. The Web API, version 0.3.5, is only used by the mobile app. The mobile app is now released on the App Store! What will the Web API version be?

Answer and Explanation
Correct answer: **0.3.5** or **1.0.0** According to the specifications: > Version 1.0.0 defines a public API. It should be released if the software is used in production or if significant dependencies exist. Explanation for each choice: - [x] Remain 0.3.5: Correct if no public use. - [ ] 0.3.6: Incorrect as no bug fix. - [ ] 0.4.0: Incorrect as no change in functionality. - [x] 1.0.0: Correct if the API is now public via the App Store.

Question 7: You changed a feature specification in version 1.12.6! It's no longer backward-compatible. What will the version number be?

Answer and Explanation
Correct answer: **2.0.0** According to the specifications: > Major version X (X.y.z | X > 0) MUST be incremented if any backward-incompatible changes are introduced to the public API. Minor and patch versions MUST be reset to 0. Explanation for each choice: - [ ] 1.12.7: Incorrect as major version must increase with incompatibility. - [ ] 1.13.0: Incorrect as major version must increase with incompatibility. - [x] 2.0.0: Correct for backward incompatibility. - [ ] 2.1.0: Incorrect; minor and patch reset with major change. - [ ] 2.12.0: Incorrect; minor and patch reset with major change.

Question 8: You changed a feature in version 0.3.6! It's no longer backward-compatible, but we are still in early development where frequent changes are expected. What's a prudent version number?

Answer and Explanation
Correct answer: **0.4.0** According to the specifications: > Major version zero (0.y.z) indicates development. Changes can occur at any time. Do not assume stability. > 1.0.0 should be released if the software is used in production or is stable and relied upon. Explanation for each choice: - [x] 0.4.0: Correct for early development, using a minor increment. - [ ] 1.0.0: Incorrect as it's still in early development.

Question 9: A bug was found in 1.5.2! You've fixed it and added a new feature without changing existing specifications. What's the version number now?

Answer and Explanation
Correct answer: **1.6.0** According to the specifications: > Minor version Y (x.Y.z | x > 0) MUST be incremented if backward-compatible functionality is added. Patch version should be reset. Explanation for each choice: - [ ] 1.5.3: Incorrect as minor must increase with functionality. - [x] 1.6.0: Correct for adding functionality. - [ ] 1.6.1: Incorrect as patch resets with a minor increment. - [ ] 2.0.0: Incorrect since changes are backward-compatible.

Question 10: After releasing version 2.6.3, a bug was immediately found and fixed in 30 seconds! What's the new version?

Answer and Explanation
Correct answer: **2.6.4** According to the specifications: > Once a versioned package is released, the contents must not be modified. Any errors must be corrected in a new version. Therefore, even if quickly adjusted, the version should be 2.6.4.

Question 11: You deprecated an API in version 1.14.3. What's the new version?

Answer and Explanation
Correct answer: **2.0.0** According to the specifications: > If any public API is deprecated, the major version must increase due to loss of backward compatibility. Explanation for each choice: - [ ] 1.14.4: Incorrect since backward compatibility is lost. - [ ] 1.15.0: Incorrect since backward compatibility is lost. - [x] 2.0.0: Correct as major version increases with deprecation.

Question 12: You plan to deprecate an API in version 1.11.1 but haven't done so yet. Documentation will mention this upcoming change. What's the version number?

Answer and Explanation
Correct answer: **1.12.0** According to the specifications: > If a public API is scheduled to be deprecated, you must increase the minor version. Explanation for each choice: - [ ] Remain 1.11.1: Incorrect since deprecation is planned, warranting a version change. - [ ] 1.11.2: Incorrect since the minor version must increase with deprecation plans. - [x] 1.12.0: Correct, as planned deprecation means bumping the minor version. - [ ] 2.0.0: Incorrect since changes are still backward-compatible.

Conclusion

The quiz format sparked quite an excitement at my workplace. Feel free to challenge your colleagues too.

If there's any mistake in this quiz, please let me know.

Thank you for participating.