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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README.md #1716

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
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
Collaborator

@katcharov katcharov May 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Are we fine with the current PR wording,

The MongoDB Java, Kotlin and Scala drivers follow semantic versioning for their releases.

then? And remove the rest of the text?

Copy link
Author

Choose a reason for hiding this comment

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

To help clarify some of the points above:
1 - As the ticket alludes to, drivers team's can choose either of the verbiages depending on their history of releases. Most drivers have mentioned the 1st statement. .NET/C# for example has been following it since v3.0.0 and hence uses the 2nd option
1.1 - I agree this is confusing and mostly re iterates what semver is.
1.2 - This is to help clarify this at a high level and hence pointing to the home page feels sufficient (This was taken from our internal policy)
1.3 I think all of this is covered by the internal policy
2 - Covered above as the focus is only on drivers.

Copy link
Member

@stIncMale stIncMale Jun 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@rishitb-mongodb

The original ticket was focused only on Drivers (We don't need it for other libraries/ODMs etc hence they weren't added).

All the artifacts we release from the https://github.com/mongodb/mongo-java-driver are related to the driver. I am certain the "follow semantic versioning" rule should be applied to all of them, but we should not list all the artifacts, because

  • there are quite a few of them, and just saying "Java, Kotlin and Scala drivers" does not cover them all;
  • the list is not fixed in stone, and if we start producing more artifacts in the future, we will likely not update the list in the readme part about the versioning, i.e., if we list the artifacts, the list may become stale.

1.2 - This is to help clarify this at a high level and hence pointing to the home page feels sufficient (This was taken from our internal policy)

I am not sure what you mean. Given that there are two different versions of semantic versioning scheme, saying/implying that we strictly follow semantic versioning is meaningless, unless the scheme version itself is also specified.

If the above seems like I am getting into the unhelpful details, then we should not say/imply that we strictly follow that specific versioning scheme.

@katcharov

Are we fine with the current PR wording,

The MongoDB Java, Kotlin and Scala drivers follow semantic versioning for their releases.

I am proposing us not to use that wording, see above.

Copy link
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.


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