Summary

Across the mongodb/specifications repository, various spec documents have a "version" field in their header. A number of older specs do not (e.g. CRUD). I'm not aware of any driver actually referencing or otherwise using these version numbers, and would consider them redundant in light of dated change log entries.

In the past, the DBX team has considered exploring how we might use versioning to automate syncing of spec tests (IIRC andreas.braun was most recently thinking about this), but apart from some old tags on the repository those ideas have never come to fruition. And it's not clear that version labels within the specs themselves would serve any purpose if such automation were to rely on git tags anyway.

While the repository does provide guidelines for versioning the drivers themselves (see: Drivers follow semantic versioning), there is practically no guidance on how to update versions for specs that have them. As a result, this leads to frequent discussions in spec PRs over how or whether to bump a spec's version (see related links).

Spec versioning only serves a purpose for the Unified Test Runner, which has versioned JSON schemas for validating test files. Additionally, that spec has clear guidelines on how to bump the version for particular changes (see: Impact of Spec Changes on Schema Version). Unfortunately, there is no guidance in the Unified Test Runner spec about bumping the version for test runner changes that have no corresponding schema change (see: this comment in mongodb/specifications#1156 for DRIVERS-1713).

I propose the following:

• Remove the "version" field from existing spec documents that have them
• Rename the Unified Test Runner spec's "version" heading to "schema version"
• Remove additional front matter from spec documents (e.g. last modified date, authors)

Motivation

Who is the affected end user?

DBX team members.

How does this affect the end user?

Contributors and reviewers frequently discuss whether particular changes in a spec warrant a minor or patch bump to the spec version. This seems like a lot of wasted consideration for something that doesn't actually serve much purpose.

Is this issue urgent?

No.

Is this ticket required by a downstream team?

No.

Is this ticket only for tests?

No.