Description
If merge A and merge B both try to increase the version from 10 to 11, git will helpfully merge both of them, resulting in the version 11 having both changes. If a nightly is released in the time between A and B are merged, then both will claim to have the save version, but with different features.
This almost happened with #94009 and #94150, but was prevented by manual noticing and intervension, which is not ideal.
We should figure out a way such that if 2 commits both attempt to merge the same increments, git will raise this as a merge conflict, so this situation wont occor again.
A way to do this would be to store in a comment the logical "latest feature"
Eg: PR Foo
-// Latest Feature: Initial release
-const FORMAT_VERSION = 1;
+// Latest Feature: Foo
+const FORMAT_VERSION = 2;
PR Bar:
-// Latest Feature: Initial release
-const FORMAT_VERSION = 1;
+// Latest Feature: Bar
+const FORMAT_VERSION = 2;
If Foo is merged, when Bar is attempted to be merged, the following conflict will occor
<<<<<<< HEAD
// Latest Feature: Foo
=======
// Latest Feature: Bar
>>>>>>> bar
const FORMAT_VERSION = 2;
This could work, but will have a problem if two features are given the same name, and then we're back to where we were. If someone knows some git-trickery to get around that, that would be great, but if not, I still thing doing this (or something to this effect) would be worthwhile.
@rustbot modify labels: +T-rustdoc +A-rustdoc-json
Activity
Dylan-DPC commentedon Mar 4, 2022
cc @rust-lang/rustdoc
GuillaumeGomez commentedon Mar 4, 2022
I'm not sure what the best solution would be here... Adding a tidy check on the version number wouldn't work in this case unless you rebased your PR. Maybe adding this comment would be better, not sure...
est31 commentedon Mar 4, 2022
You could make a
const FORMAT_CHANGELOG = ["Initial version", "Done foo", "Done bar", ...];
, and then require PRs that change the version to add to that list. Then you could haveconst FORMAT_VERSION = FORMAT_CHANGELOG.len();
. Or you could alternatively do it with PR numbers, but those are not known upon filing.camelid commentedon Mar 4, 2022
Do we definitely need a format version?
aDotInTheVoid commentedon Mar 5, 2022
Anacdotaly it is used to detect when the json moves, which does happen quite a bit:
https://github.com/awslabs/smithy-rs/blob/d823f61156577ab42590709627906d1dc35a5f49/tools/api-linter/src/cargo.rs#L78-L96
Iff and when where talking about stabilization, we should reconsider, but I think it works well for now
aDotInTheVoid commentedon Mar 5, 2022
cc @hkmatsumoto @jdisanti @Urgau @maan2003 @akiross @Enselic: Do you use
FORMAT_VERSION
, and if not why? Would you like a fuller changelog, just a number, or nothing at all?notriddle commentedon Mar 5, 2022
Instead of names, pull request URLs?
Urgau commentedon Mar 5, 2022
No, not yet; I just didn't found the time and the right way to get it but the solution from
smithy-rs
is quite simple so I've use it.Yes, a changelog would be useful but I don't think it's not required. The format number is good no need for more.
I would just like to have a recommended way to get and check it. The
smithy-rs
solution could maybe be integrated in the crate?camelid commentedon Mar 5, 2022
I think the issue with that is that you can't determine it before opening a PR, but we could have people just update that after opening their PR maybe?
Enselic commentedon Mar 6, 2022
I currently do not make direct use of
FORMAT_VERSION
, but I think there is value in keeping it anyway.There are several reasons I don't make direct use of it:
FORMAT_VERSION
12" no one knows what that means. Whereas if I say "you need at least nightly-2022-03-04" people know what that means.FORMAT_VERSION
, which made nightly version the most accurate identifier anywayFORMAT_VERSION
s. For example,FORMAT_VERSION = 12
output can be read by code that assumeFORMAT_VERSION = 11
, because12
only added fields/properties to existing structs. So requiringFORMAT_VERSION
to be the same would be unnecessarily limiting.That said, I think there is value in keeping
FORMAT_VERSION
, because it:The risk of two features having the same logical name is low, but can be eliminated by scoping with username:
I'm not a big fan of having to force push directly after creating a PR to update with the PR number.
I think the single number
FORMAT_VERSION
suffices for now. No need for a changelog for example. But I agree that when it is time to prepare rustdoc JSON for stabilization, there is a clear need for something more formal. Maybe semver, although it is not clear to me we could ever change MAJOR in such a version scheme when rustdoc JSON reaches stable.akiross commentedon Mar 7, 2022
Regarding my usage: no, I don't use
FORMAT_VERSION
yet, simply because I tailored my tool on a specific version and I did not care at the time of writing, but if I had to make the tool public (which is planned) I'd definitely depend on it.Changelog is probably unnecessary for my purposes, but I agree on the fact that something more structured than a single number could be more useful on the long run, and semver could make sense... Although this does not (deterministically) solve the problem of conflicting increments in the number if it remains confined in the code.
Regarding the problem itself, I don't see a solid solution which doesn't use git-related information (e.g. the hash of the commit that last changed a particular file or that changed the
FORMAT_VERSION
value). Automation could be put in place here, but it's on a different level, not on the code (e.g. a hook that prevents a merge if theFORMAT_VERSION
was changed in two different commits with the same value).On a higher level, if this kind of feature is needed at all... Typically if a software library produces different outputs given the same input, its semver should change... So, in principle, if that happened to rustdoc's (json) output, wouldn't be this a change in rustdoc's version? OTOH, having the version number in the output json moves the issue of parsing the json to the consumer level, which could support multiple versions, which might be desirable for various reasons. It seems to me that a "clean solution" would be to change rustdoc's semver if the json output changes, but also include that same version in the produced json file.
... But I'm sure this solution would conflict with many other things I'm not aware of, so just take it as my humble and ignorant perspective.
jdisanti commentedon Mar 7, 2022
I use
FORMAT_VERSION
to be notified of changes to the JSON format so that I can make sure my tool is working correctly with those changes. If you wanted to use a list of feature names, that works for me too since I could just compare the last known feature name with the end of that list.Thinking about it more though, I don't absolutely need a format version or change log since I have a comprehensive test suite that should detect any breaking changes to the format that actually impact my tool.
18 remaining items