Implemented suggestions from Pierre-Antoine for our submission doc #6
Loading…
Add table
Reference in a new issue
No description provided.
Delete branch "master"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
The TOC is strange
sections 1 and 2 are in bold, but section 3 and 4 are not **--> ACTION: Bolded section 3 and 4 **
it contains unexisting sections "Conformance" and "Normative References" --> ACTION: commented out these two
Section 1 is grammatically incorrect. --> ACTION: added the suggestion below
A a verb ("increment" probably) is missing after "MAJOR.MINOR.PATCH-EXTRA+META". That's at least how it is phrased in semver.org .
Section 1: "EXTRA Has" → "EXTRA has" --> ACTION: corrected it
Section 2: RFC2119 has been updated by RFC8174. The reference to RFC2119 should read instead:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
appear in all capitals, as shown here. --> ACTION: added the suggestion completely
Since the text contains a number of "must", "may" and "should" in lowercase, you probably want to check them systematically and uppercase those that need to be normative **--> ** ACTION: uppercased them
Section 2, item 9: "pre-release version" should probably be "extra version". --> ACTION: corrected it
Section 2, item 9 of the first list: missing space between "[0-9A-Za-z-]." and "Identifiers" --> ACTION: corrected it
Section 2, item 11: "pre-release fields" should be "extra identifiers" (the former is not defined anywhere) --> ACTION: corrected it
Section 2.1, 1st paragraph, last sentence: contains the word "still" twice, one should be removed. Also, I would add "that" after "recommended", to make the sentence easier to parse. --> ACTION: corrected both of them
Section 2.1, advisement block: "components being versions" should probably be "components being versioned" --> ACTION: corrected it
Section 2.1: the term "bump" (and its derivative) is used in some places as a synonym(?) of "increment". You should probably replace it. --> ACTION: corrected it only at 2.1 - Also reformulated similar sentences in 2.1.5, which needs your approval
Section 2.1.1 does not mention "deprecating public functionalties" under MINOR, also the global list at the top of Section 2 does. This is confusing and should be fixed. --> ACTION: added an extra sentence at the end of MINOR, needs your approval
Section 2.1.1 "This specification guarantees backward compatibility with version 2.0" → I assume that you mean "with semver.org version 2.0". --> ACTION: corrected it
Section 2.1.3, first sentence: this sentence has no main verb. --> ACTION: reformulated the sentence, needs your approval
Section 2.1.3: the parenthesis "(see schema versioning below)" should appear after the first mention of schema versioning (i.e. in the bullet about PATCH or even in the advisement block above). Alternatively, it could be present after each mention of schema versioning. --> ACTION: added it in the first sentence of the section
Section 2.1.3: I don't know what it means to be "backward compatible" for a change in a dataset... I have a few ideas about how to define it, but I don't know if that's what YOU mean. And maybe what you mean is "it's up to the reader to decide what backward compatible means", but even that should be explicit in a note or something. --> ACTION: added a note to explain this, TOTALLY NEEDS YOUR APPROVAL
Section 2.1.4, first sentence: this sentence has no main verb. --> ACTION: reformulated the first two sentences, needs your approval
Section 2.1.5: "should be versioned separate" → "should be versioned separately" --> ACTION: corrected it
Section 2.1.5: "Each versioned public component receives a version that is independent and according to the rules of it’s versioning class." --> NO ACTION: I think that's for you
this sentence may be seen to contradict itself:
the rules for dataset require that version changes in the schema impact the version of the datatset -- so they are not independant, strictly speaking
maybe find a better way to phrase this?
Section 2.1.5, example would be clearer if presented as a table, with 3 column sclearly headed "composite artifact", "component 1" and "component 2" --> ACTION: commented the example out, added the table as per suggestion, needs your approval
Section 2.1.5: "Bumping at most one version step." → this sentence has no main verb, I suspect it is part of the preceding sentence, and therefore should be separated with a comma (",") rather than a period ("."). --> ACTION: corrected it
Section 2.2: "to the version it is written against" → "to the version of another software it is written agains" or "to the version of another software on which it depends" --> ACTION: corrected it
Section 2.2, item 2 : "Such that." → ?? --> ACTION: Deleted it.
Section 3: "pre-release" should be replaced everywhere in the grammar with "extra", to be consistent with the text above --> ACTION: replaced it everywhere
Section Reference is empty ; why keep it, then? --> ACTION: Commented it out.
changed title from {-Line by line update-} to {+Implemented suggestions from Pierre-Antoine for our submission doc+}
In the document submitted to the W3C keep this, but for this document this and similar stuff int he header needs to be like we originally had it because the formatting between the two is a bit different.
All the above authoer stuff needs to be int he orignal format, but keep it changed int he W3C document, this is a formatting thing.
This extra fields that werent originally there wont work int he header, keep them in the W3C submited doc but can remove them from here.
Not sure what lines 238 to 246 are about. Did you mean to add those? Looks like something pulled in fromt he HTML that may not supposed to be here.
lines 248 to 270 look like example versions that are supposed to be in an example box somewhere. They may have gotten erroneously copied over when you converted from HTML or something?
requested changes
Ah, I thought it just wasn't updated. These are the 'chunks' I thought this document was missing.
Yeah, I get it now, just thought it is missing. Didn't know there was a format difference, although I should have detected that maybe.
Ok
This is just the same example but put in a table format, as Pierre-Antoine suggested. Apparently the wrong format, but it was supposed to show a table.
This was supposed to be the content for the table's cells.
changed this line in version 2 of the diff
changed this line in version 2 of the diff
changed this line in version 2 of the diff
changed this line in version 2 of the diff
changed this line in version 2 of the diff
added 1 commit
f81dac0a- Latest version update after Jeffrey's inputCompare with previous version
added 1 commit
124a86cd- Update _index.mdCompare with previous version
changed title from {-Implemented suggestions from Pierre-Antoine for our submission doc-} to {+Update_index1+}
changed title from {-Update_index1-} to {+Implemented suggestions from Pierre-Antoine for our submission doc+}
Extra space in front not needed. Im not sure if the YAML format used here will care about the space, functionally I think it would work. But generally we dont want white space changes in our MR that arent intentional (and even then usually as a seperate MR) otherwise it pollutes the commit history.
So if the goal here is to just put it on the same line so it matches the w3C version then we would use single tics instead of the triple tics. So should be this (make sure the tic marks do not get back into the W3C version)
Given a version number
MAJOR.MINOR.PATCH-EXTRA+META, increment the:The dash here doesnt seem to be appropriat eto english. Typically we would use a comma here. Were these dashes suggestion from pierre or your own addition?
Some minor comments before submitting.
requested changes
This is an appropriate use of em dashes. Commas or parentheses would also be fine.
While we're fixing up the grammar:
Are we sure we want to change the apostrophe here? I think the ASCII one was preferable.
Grammar issue: these are two independent clauses, so a comma splice is inappropriate. Some options:
It might be worth linking this (
[Schema Versioning](#schema-versioning)) or at least capitalizing it, since it's the title of a section.It was my addition. Will correct it.
Hold on may not need to correct it. Seems Kyle taught me something, "Em dashes" are a new concept to me, just learned something new in english. Despite my horrible online spelling I'm usually pretty decent at grammar, im amazed I got to learn something new. For now you can keep this while I read up on this new gramatical structure. Given the confusing nature of the other commas this may be a great use for this. Though from what im reading I think they need to be a long-dash (also called double dashes) and not a regular hyphen like you have.
Despite common beleif training prepositions are actually considered acceptable english. Not being an expert on such things ill defer to this article:
https://www.grammarly.com/blog/sentences/end-sentence-preposition/#:~:text=Is%20it%20OK%20to%20end,acceptable%E2%80%94it's%20the%20best%20option.
Honestly to me they look like the same apostrophe.. but I think kyle is right, the one we already had was more likelyt he correct one since Eugene is on a non-english keyboard.
Agreed
Agreed, makes it easier as a link.
By the way Eugene needs to translate this over to the version he is submiting to the w3c which uses html. So obviously doing that over there will be different and he doesnt know html, you may need to show him how to add that.
I believe they're Unicode em dashes (U+2014), which are hard to distinguish from hyphens in the monospaced text view but readily apparent in the rendered Markdown.
I think this qualifies as "formal communication", which is one of the circumstances in which that article says it's inappropriate to have a trailing preposition.
Done.
Done.
Ok, let it with dashes. Done.
"the version against which it is written". Done.
Done.
kind, of which both. Done.
He did, and grateful for that. Done.
changed this line in version 5 of the diff
changed this line in version 5 of the diff
changed this line in version 5 of the diff
changed this line in version 5 of the diff
changed this line in version 5 of the diff
added 1 commit
05c40b71- Update _index.mdCompare with previous version
approved this merge request
added 1 commit
a466599b- Update _index.mdCompare with previous version
reset approvals from @freemo by pushing to the branch
added 1 commit
862b4fb1- Update _index.mdCompare with previous version
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.