[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: |
|
||||||||||||||||||||||||
| Driver Changes: | Not Needed | ||||||||||||||||||||||||
| Description |
SummaryAcross 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:
MotivationWho 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: 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.
This is no longer relevant since spec versions and last modified dates were removed from front matter.
|
| Comment by Jeremy Mikola [ 05/Oct/22 ] |
| Comment by Jeremy Mikola [ 04/Oct/22 ] |
Per the Causal Consistency spec, possible values are:
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:
|
| 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:
|