Update Gem::Version documentation#9535
Open
jeremyevans wants to merge 3 commits into
Open
Conversation
Explain optimistic and pessimistic versioning, give an example of problems with each (replacing the example with the overly simplistic Stack class), and recommend optimistic versioning. Switch from "build" to "patch" when describing the z in x.y.z versioning. Remove Preventing Version Catastrophe section, which only affects you if you are using pessismistic versioning.
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation-only update to Gem::Version's rdoc comments. Replaces the prior Stack-based version examples and "Preventing Version Catastrophe" section with a new explanation contrasting Optimistic vs. Pessimistic dependency versioning, recommending optimistic versioning in most cases (per a recent developer meeting decision). Also renames the third version component from "build" to "patch" in the Rational Versioning section.
Changes:
- Simplifies the "How Software Changes" section, removing the Stack-class examples and condensing it to three categories of changes.
- Renames the third version component from "build" to "patch" and tightens the Rational Versioning bullets.
- Adds a new "Optimistic Vs. Pessimistic Dependency Versioning" section with an extended example arguing for optimistic versioning.
Comments suppressed due to low confidence (6)
lib/rubygems/version.rb:84
- Typo: "softaware" should be "software".
# the softaware, and that patch or minor releases of a dependency will not
lib/rubygems/version.rb:89
- Grammar: "optimistic version is superior to pessimistic versioning" — "version" should be "versioning" for parallelism.
# In general, optimistic version is superior to pessimistic versioning.
lib/rubygems/version.rb:104
- Duplicated word: "not not diligent" should be "not diligent".
# significant problems if that library is not not diligent about updating
lib/rubygems/version.rb:100
- Grammar: this sentence is missing an object. "the software does not require any changes in order to use" should be "the software does not require any changes in order to use it".
# dependency will release a new major version and the software does not require
# any changes in order to use. In this case, being pessimistic requires
lib/rubygems/version.rb:154
- Typo: "pessismistic" should be "pessimistic".
# Both optimistic versioning and pessismistic versioning have problems in
lib/rubygems/version.rb:159
- Grammar: "If the dependency is library that adds a single method" is missing an article. It should be "If the dependency is a library that adds a single method".
# That is not to say that pessimistic versioning is never appropriate. If the
# dependency is library that adds a single method, where any change resulting
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # version number and reset the build number. | ||
| # version number and reset the patch number. | ||
| # | ||
| # * A category 3 change (incompatible) will increment the major build number |
| # == RubyGems Rational Versioning | ||
| # | ||
| # * Versions shall be represented by three non-negative integers, separated | ||
| # by periods (e.g. 3.1.4). The first integers is the "major" version |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was the end-user or developer problem that led to this PR?
Add the recent developer meeting, we discussed switching from using pessimistic versioning by default to using optimistic versioning by default.
What is your fix for the problem, implemented in this PR?
This updates the documentation to explain the differences between pessimistic and optimistic versioning and recommend optimistic versioning in most cases.
Make sure the following tasks are checked