Skip to content

Update README.md #1716

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 9, 2025
Merged

Update README.md #1716

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7d9c6f1
Update README.md
rishitb-mongodb May 22, 2025
d750626
Merge branch 'mongodb:main' into updated-readme
rishitb-mongodb Jun 5, 2025
615d2d5
Update README.md
rishitb-mongodb Jun 5, 2025
8388357
Merge branch 'mongodb:main' into updated-readme
rishitb-mongodb Jun 6, 2025
d9e3630
Update README.md
rishitb-mongodb Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ MongoDB project, please report it according to the [instructions here](https://w

## Versioning

The MongoDB Java, Kotlin and Scala drivers follow [semantic versioning](https://semver.org/) for their releases.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • We produce more libraries than just the drivers from this repository, and there is no reason to list them all here in the "Versioning" section.
  • We try to follow semantic versioning, but I don't believe we have never violated it, or guarantee that we will never violate it.

Let's rephrase to something like

Suggested change
The MongoDB Java, Kotlin and Scala drivers follow [semantic versioning](https://semver.org/) for their releases.
We generally follow [semantic versioning(https://semver.org/) when releasing.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rishitb-mongodb @stIncMale Note that the ticket says:

This will help foster confidence that we do strictly follow semantic versioning even though it might be obvious from our past releases.

Copy link
Member

@stIncMale stIncMale May 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. In that case, let's use the option B suggested in the ticket, specifying 5.6.0 as the "since" version. And say that historically the driver generally followed semantic versioning, but may not always had followed it strictly. I vaguely remember us talking about some changes technically requiring a more severe version change, but deciding not to do that.
    1.1. We also should remove all the text from the "Versioning" section of the readme, leaving there only the information about us following semantic versioning. Having that text will only introduce confusion, unless the text is identical to the semantic versioning specification.
    1.2. Semantic versioning specification itself has versions, and since the intent is to promise that we'll follow it strictly, we should specify the semantic versioning version and link to it (https://semver.org/spec/v2.0.0.html), instead of vaguely referring to semantic versioning as an idea. DRIVERS-3105 fails to require this, but I don't think it is possible to talk about strict compliance without specifying the spec version being complied with.
    1.3. I guess, we'll have to be much more careful with releases, and carefully read all the rules of the versioning scheme.
  2. The suggestion about not listing all the libraries we produce from this codebase is still relevant.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can safely say that we've been strictly following semantic versioning since at least the 3.0 release.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should I change this to "The MongoDB Java, Kotlin and Scala drivers follow semantic versioning since v3.0.0 of their releases."? The original ticket was focused only on Drivers (We don't need it for other libraries/ODMs etc hence they weren't added).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stIncMale What other artefacts are you alluding to? We are focused on making this change ONLY for drivers and hence the drivers that are a part of this repo were added to the statement.

Could you clarify what the suggestion is then? If I understood correctly, it is to:

  1. Remove all current text under the "Versioning" section of the Readme and
  2. Replace it with "We generally follow semantic versioning when releasing."

Copy link
Member

@stIncMale stIncMale Jun 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you clarify what the suggestion is then?

  1. Avoid listing all the artifacts we release from the https://github.com/mongodb/mongo-java-driver repository.
  2. Link to https://semver.org/spec/v2.0.0.html, which actually specifies the semantic versioning scheme, instead of linking to https://semver.org, which makes it ambiguous which version of the semantic versioning scheme we follow.
  3. Remove the text highlighted here.

What other artefacts are you alluding to?

Following is the list of all artifacts (groupId:artifactId) we produce (one may also see them in our BOM):

org.mongodb:bson
org.mongodb:bson-record-codec
org.mongodb:mongodb-driver-core
org.mongodb:mongodb-crypt
org.mongodb:mongodb-driver-sync
org.mongodb:mongodb-driver-reactivestreams
org.mongodb:mongodb-driver-legacy
org.mongodb.scala:mongo-scala-bson_2.11
org.mongodb.scala:mongo-scala-bson_2.12
org.mongodb.scala:mongo-scala-bson_2.13
org.mongodb.scala:mongo-scala-driver_2.11
org.mongodb.scala:mongo-scala-driver_2.12
org.mongodb.scala:mongo-scala-driver_2.13
org.mongodb:bson-kotlin
org.mongodb:bson-kotlinx
org.mongodb:mongodb-driver-kotlin-sync
org.mongodb:mongodb-driver-kotlin-coroutine
org.mongodb:mongodb-driver-kotlin-extensions
org.mongodb:mongodb-driver-bom

Different intersecting subsets of them represent the following products we provide:

  • Java legacy driver
  • Java synchronous driver
  • Java reactive streams driver
  • Scala driver
  • Kotlin synchronous driver
  • Kotlin coroutine driver
  • BSON library
    • One may argue that this is not considered a product because there is no documentation page dedicated to it. But "Java legacy driver" also does not have a dedicated page. Furthermore, "BSON library" is an implementation of https://bsonspec.org/spec.html, which may be considered a self-sufficient product.
    • Update: Actually, I found that we list this library here among other BSON implementations, and explicitly call it a "standalone BSON library", i.e., it is a product.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated based on suggestions

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I proposed the "generally" phrasing only in the beginning of the thread, before I knew that the idea was to express strict adherence. The answer to the "Could you clarify what the suggestion is then?" question did not propose to say "generally". Thus, let's remove it from text.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I misunderstood that, fixed.


Major increments (such as 4.x -> 5.x) will occur when breaking changes are being made to the public API. All methods and
classes removed in a major release will have been deprecated in a prior release of the previous major release branch, and/or otherwise
called out in the release notes.
Expand Down