[DRIVERS-2253] Remove spec versions and front matter Created: 30/Mar/22  Updated: 28/Oct/23  Resolved: 06/Oct/22

Status: Closed
Project: Drivers
Component/s: None
Fix Version/s: None

Type: Task Priority: Unknown
Reporter: Jeremy Mikola Assignee: Jeremy Mikola
Resolution: Fixed Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to DRIVERS-2626 Better clarify schema version changes Backlog
related to DRIVERS-2463 Use consistent ordering for changelog... Backlog
related to DRIVERS-2461 Use field list syntax for Change Stre... Closed
related to DRIVERS-2462 Use field list syntax for CSFLE spec ... Closed
related to DRIVERS-2273 Clarify schema versioning for Unified... Backlog
Driver Changes: Not Needed

 Description   

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.



 Comments   
Comment by Githook User [ 06/Oct/22 ]

Author:

{'name': 'Jeremy Mikola', 'email': 'jmikola@gmail.com', 'username': 'jmikola'}

Message: DRIVERS-2253: Remove spec front matter and reformat changelogs (#1311)

This limits front matter fields to "Status" and "Minimum Server Version".

Spec versions were removed across the board, excluding the Unified Test Format, which retained a field for "Current Schema Version". The only other spec where versioning was somewhat relevant was Extended JSON, and the transition from 1.0 to 2.0 is clearly noted in the changelog (minor versions since 2.0 were not relevant).

Apart from the deprecated Bulk API spec, all specs have an "Accepted" status. Some were incorrectly listed as "Draft".

This also revises changelogs across all specs to use "Field List" formatting (like spec front matter). The CSFLE and Change Stream specs were left as-is, since they used CSV and grid tables, respectively. Some existing changelog entries were incorrectly ordered and fixed. Lastly, specs were inconsistent in whether changelogs entries used ascending or descending date order, so existing order was left in place when possible. For some very old specs without dated changelog entries, dates were inferred from git history.

  • Removes PR template reminder to bump spec version/lastmod.

This is no longer relevant since spec versions and last modified dates were removed from front matter.

  • Consistently refer to "changelog" instead of "change log"
  • Remove versionadded macros from CSFLE spec
Comment by Jeremy Mikola [ 05/Oct/22 ]

https://github.com/mongodb/specifications/pull/1311

Comment by Jeremy Mikola [ 04/Oct/22 ]

we have definitely had specs that lived in this repo for some time that were not finalized, though I'm open to rethinking what the list of statuses should be

Per the Causal Consistency spec, possible values are:

  • Draft
  • Accepted (some specs use Approved)
  • Rejected
  • Final
  • Replaced

I believe these came from a Google Docs template and only a subset of these actually appear in the repository.

Comment by Martin Bajana [ 11/Jul/22 ]

jmikola@mongodb.com Can you review Bernie's note and take this forward.  Thanks

Comment by Bernie Hackett [ 06/Jul/22 ]

I'm generally in agreement with jeff.yemin@mongodb.com that we should remove most of the front matter. The format of that table came from the Python PEP format, which I liberally borrowed from when coming up with the spec format. Most of the fields aren't useful, and I don't even remember why some of them exist (the spec number, for example).

That said, two of the fields are useful and I think we should keep them:

  • Minimum Server Version
  • Status (we have definitely had specs that lived in this repo for some time that were not finalized, though I'm open to rethinking what the list of statuses should be)
Comment by Jeremy Mikola [ 11/Apr/22 ]

Repurposed this issue to only discuss removal of spec versions and front matter.

Schema versioning changes for the Unified Test Runner have been split off to DRIVERS-2273.

Comment by Matt Dale [ 30/Mar/22 ]

I support this proposal. I generally ignore the spec versions because they don't tell me anything meaningful.

Comment by Jeremy Mikola [ 30/Mar/22 ]

Note: if there is no consensus to remove versions from existing specs, I'd propose either repurposing this ticket or splitting off the suggested change to the Unified Test Runner:

Update the Unified Test Runner spec to clearly state that the schema version should be increased for test runner changes, even if the schema itself is not changed. In this case, the previous schema should be copied without changes (e.g. schema-1.7.json is copied to schema-1.8.json and tests that depend on changed behavior in 1.8 should require that schema version).

Generated at Thu Feb 08 08:25:07 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.