README: note [email protected]
PATCH 1/1 README: note [email protected]
Add a mention of the security mailing list to the README. 2caa7b8d27 ("git manpage: note [email protected]", 2018-03-08) already added it to the man page, but I suspect that for many developers, such as myself, the README would be the first place to go looking for it.
Use the same wording as we already have on the git-scm.com website and in the man page.
---
2caa7b8d27 ("git manpage: note [email protected]", 2018-03-08) also mentions SubmittingPatches, but I think people are much more likely to submit a report of a security issue first, rather than sending a patch, for which I think the README is more useful.
README.md | 3 +++ 1 file changed, 3 insertions(+)
README.md +3 -0
@@ -36,6 +36,9 @@ the body to [email protected]. The mailing list archives are available at <https://public-inbox.org/git/>, <http://marc.info/?l=git> and other archival sites. +Issues which are security relevant should be disclosed privately to +the Git Security mailing list <[email protected]>. + The maintainer frequently sends the "What's cooking" reports that list the current status of various development topics to the mailing list. The discussion following them give a good reference for
Signature · 1 line
2.17.0.921.gf22659ad46
Quoted 6 lines · Thomas Gummerer
Add a mention of the security mailing list to the README.
2caa7b8d27("git manpage: note [email protected]", 2018-03-08) already added it to the man page, but I suspect that for many developers, such as myself, the README would be the first place to go looking for it.
Quoted 7 lines
Use the same wording as we already have on the git-scm.com website and in the man page.
Signed-off-by Thomas Gummerer <[email protected]>--- README.md | 3 +++ 1 file changed, 3 insertions(+)
Quoted 4 lines
2caa7b8d27("git manpage: note [email protected]", 2018-03-08) also mentions SubmittingPatches, but I think people are much more likely to submit a report of a security issue first, rather than sending a patch, for which I think the README is more useful.
I don't see a mention of SubmittingPatches in "git show 2caa7b8d27" output. git help git tells me:
Report bugs to the Git mailing list <[email protected]> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there.
Issues which are security relevant should be disclosed privately to the Git Security mailing list <[email protected]>.
Do you mean that the discussion around that change suggested updating SubmittingPatches too? The "Sending your patches" section indeed mentions [email protected], so a mention of the security list would indeed be welcome there, even though typically the discussion has already started there before a patch is written.
Thanks,
Jonathan
[PATCH 2/1] SubmittingPatches: not [email protected]
Quoted 11 lines · Jonathan Nieder
Quoted 9 lines · Thomas Gummerer
Add a mention of the security mailing list to the README.
2caa7b8d27("git manpage: note [email protected]", 2018-03-08) already added it to the man page, but I suspect that for many developers, such as myself, the README would be the first place to go looking for it.Use the same wording as we already have on the git-scm.com website and in the man page.
Quoted 6 lines
Quoted 4 lines
Signed-off-by Thomas Gummerer <[email protected]>--- README.md | 3 +++ 1 file changed, 3 insertions(+)Reviewed-by Jonathan Nieder <[email protected]>
Thanks!
Quoted 17 lines
Quoted 4 lines
2caa7b8d27("git manpage: note [email protected]", 2018-03-08) also mentions SubmittingPatches, but I think people are much more likely to submit a report of a security issue first, rather than sending a patch, for which I think the README is more useful.I don't see a mention of SubmittingPatches in "git show
2caa7b8d27" output. git help git tells me:Report bugs to the Git mailing list <[email protected]> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there.
Issues which are security relevant should be disclosed privately to the Git Security mailing list <[email protected]>.
Quoted 5 lines
Do you mean that the discussion around that change suggested updating SubmittingPatches too? The "Sending your patches" section indeed mentions [email protected], so a mention of the security list would indeed be welcome there, even though typically the discussion has already started there before a patch is written.
Yeah sorry, that's what I meant.
https://public-inbox.org/git/[email protected]/
is the reference I meant to put there.
How about something like the below? This is tested with asciidoc 8.6.10 and asciidoctor 1.5.6.2. I'm also happy to squash the two patches into one if that's preferred.
--->8---
The previous commit added a note about the Git Security mailing list to the README. Add it to Documentation/SubmittingPatches as well, so developers trying to submit a security relevant patch are pointed in the right direction.
The wording is adjusted slightly compared to the git-scm.com website and the README, as they are talking about issues, while SubmittingPatches is talking about patches.
--- Documentation/SubmittingPatches | 5 +++++ 1 file changed, 5 insertions(+)
Documentation/SubmittingPatches +5 -0
@@ -264,6 +264,11 @@ people who are involved in the area you are touching (the `git contacts` command in `contrib/contacts/` can help to identify them), to solicit comments and reviews. +:1: footnote:[The Git Security mailing list: [email protected]] + +Patches which are security relevant should be submitted privately to +the Git Security mailing list{1}. + :1: footnote:[The current maintainer: [email protected]] :2: footnote:[The mailing list: [email protected]]
Signature · 1 line
2.17.0.921.gf22659ad46
Re: [PATCH 2/1] SubmittingPatches: not [email protected]
Quoted 8 lines · Thomas Gummerer
Yeah sorry, that's what I meant.
https://public-inbox.org/git/[email protected]/
is the reference I meant to put there.How about something like the below? This is tested with asciidoc 8.6.10 and asciidoctor 1.5.6.2. I'm also happy to squash the two patches into one if that's preferred.
If the discussion in the proposed log message needs to be updated anyway, it is a good opportunity to make them into a single patch, as they share exactly the same objective.
This is a tangent, but the use of footnote below looks a but curious. How would {1} reference pick which :1: to use? The closest preceding one?
As this appears on a page that already has other footnotes attached to an adjacent paragraph, I am wondering if they should be made into a part of the same numbering sequence.
Documentation/SubmittingPatches people who are involved in the area you are touching (the `git · line 273
Quoted 11 lines
Documentation/SubmittingPatches +5
-0@@ -264,6 +264,11 @@ people who are involved in the area you are touching (the `git contacts` command in `contrib/contacts/` can help to identify them), to solicit comments and reviews. +:1: footnote:[The Git Security mailing list: [email protected]] + +Patches which are security relevant should be submitted privately to +the Git Security mailing list{1}. + :1: footnote:[The current maintainer: [email protected]] :2: footnote:[The mailing list: [email protected]]
Also, the placement of this new paragraph is rather odd.
I am guessing that the reason why you put it _before_ the normal list address is to make sure those with secrets that must be guarded won't send it to the list first without thinking, but then this place is too late for that, as the previous paragraph already told the reader that the patch should be sent to the list and others but not necessarily to the maintainer. This should go one paragraph before that, at least. I briefly considered suggesting to move it even earlier, e.g. the beginning of "Sending your patches" section, but then by the time readers with potential security patches may have forgotten it, or worse, get confused by us, when we say "Send your patches with To: set to the list". So I dunno. The most conservative would be to write it at the beginning of the section and then repeat it just before "Send to the list, Cc releavant people" paragraph as a reminder.
Re: [PATCH 2/1] SubmittingPatches: not [email protected]
Quoted 6 lines · Junio C Hamano
Quoted 4 lines · Thomas Gummerer
Yeah sorry, that's what I meant.
https://public-inbox.org/git/[email protected]/
is the reference I meant to put there.
Quoted 8 lines
Quoted 4 lines
How about something like the below? This is tested with asciidoc 8.6.10 and asciidoctor 1.5.6.2. I'm also happy to squash the two patches into one if that's preferred.
If the discussion in the proposed log message needs to be updated anyway, it is a good opportunity to make them into a single patch, as they share exactly the same objective.
This was mostly a clarification of the note I added after the '---', but I'm happy to just make this one patch either way.
Quoted 3 lines
This is a tangent, but the use of footnote below looks a but curious. How would {1} reference pick which :1: to use? The closest preceding one?
Tbh I didn't look at the docs for doing this, but just used the same syntax as we're already using and tried it with both asciidoc and asciidoctor. And yes it seems like it always picks the preceeding one.
Quoted 3 lines
As this appears on a page that already has other footnotes attached to an adjacent paragraph, I am wondering if they should be made into a part of the same numbering sequence.
I have now actually looked at the docs, and this numbering has nothing to do with the footnote format, but rather is used to substitute the attribute that's specified in the curly braces with the text that's after :<attribute>: [1]. This initially confused me a bit. Maybe it would be nicer to give the attributes names instead of just numbers? As we keep adding footnotes, that would be less likely to produce conflicts between the different attributes I think.
I'm also adding brian to the cc list, as he first converted this to AsciiDoc for opinions.
[1]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
Quoted 14 lines
Documentation/SubmittingPatches people who are involved in the area you are touching (the `git · line 273
Quoted 11 lines
Documentation/SubmittingPatches +5
-0@@ -264,6 +264,11 @@ people who are involved in the area you are touching (the `git contacts` command in `contrib/contacts/` can help to identify them), to solicit comments and reviews. +:1: footnote:[The Git Security mailing list: [email protected]] + +Patches which are security relevant should be submitted privately to +the Git Security mailing list{1}. + :1: footnote:[The current maintainer: [email protected]] :2: footnote:[The mailing list: [email protected]]Also, the placement of this new paragraph is rather odd.
Quoted 14 lines
I am guessing that the reason why you put it _before_ the normal list address is to make sure those with secrets that must be guarded won't send it to the list first without thinking, but then this place is too late for that, as the previous paragraph already told the reader that the patch should be sent to the list and others but not necessarily to the maintainer. This should go one paragraph before that, at least. I briefly considered suggesting to move it even earlier, e.g. the beginning of "Sending your patches" section, but then by the time readers with potential security patches may have forgotten it, or worse, get confused by us, when we say "Send your patches with To: set to the list". So I dunno. The most conservative would be to write it at the beginning of the section and then repeat it just before "Send to the list, Cc releavant people" paragraph as a reminder.
Yeah I wasn't quite sure where to best fit this in. I'd be happy with it appearing twice. Will update this in v2.
Re: [PATCH 2/1] SubmittingPatches: not [email protected]
Quoted 40 lines · Thomas Gummerer
Quoted 6 lines · Junio C Hamano
Quoted 4 lines · Thomas Gummerer
Yeah sorry, that's what I meant.
https://public-inbox.org/git/[email protected]/
is the reference I meant to put there.Quoted 8 lines
Quoted 4 lines
How about something like the below? This is tested with asciidoc 8.6.10 and asciidoctor 1.5.6.2. I'm also happy to squash the two patches into one if that's preferred.
If the discussion in the proposed log message needs to be updated anyway, it is a good opportunity to make them into a single patch, as they share exactly the same objective.
This was mostly a clarification of the note I added after the '---', but I'm happy to just make this one patch either way.
Quoted 3 lines
This is a tangent, but the use of footnote below looks a but curious. How would {1} reference pick which :1: to use? The closest preceding one?
Tbh I didn't look at the docs for doing this, but just used the same syntax as we're already using and tried it with both asciidoc and asciidoctor. And yes it seems like it always picks the preceeding one.
Quoted 3 lines
As this appears on a page that already has other footnotes attached to an adjacent paragraph, I am wondering if they should be made into a part of the same numbering sequence.
I have now actually looked at the docs, and this numbering has nothing to do with the footnote format, but rather is used to substitute the attribute that's specified in the curly braces with the text that's after :<attribute>: [1]. This initially confused me a bit. Maybe it would be nicer to give the attributes names instead of just numbers? As we keep adding footnotes, that would be less likely to produce conflicts between the different attributes I think.
Quoted 2 lines
I'm also adding brian to the cc list, as he first converted this to AsciiDoc for opinions.
Now really adding the CC, I failed earlier. Sorry about the noise.
Re: [PATCH 2/1] SubmittingPatches: not [email protected]
In reply to Thomas GummererQuoted 9 lines · Thomas Gummerer
Quoted 3 lines · Junio C Hamano
This is a tangent, but the use of footnote below looks a but curious. How would {1} reference pick which :1: to use? The closest preceding one?
Tbh I didn't look at the docs for doing this, but just used the same syntax as we're already using and tried it with both asciidoc and asciidoctor. And yes it seems like it always picks the preceeding one.
Yes, I believe the attributes namespace is flat and substituted using the current version that's defined. I wouldn't rely extensively on that, though, so unique names are probably better.
Quoted 4 lines
Quoted 3 lines
As this appears on a page that already has other footnotes attached to an adjacent paragraph, I am wondering if they should be made into a part of the same numbering sequence.
Quoted 9 lines
I have now actually looked at the docs, and this numbering has nothing to do with the footnote format, but rather is used to substitute the attribute that's specified in the curly braces with the text that's after :<attribute>: [1]. This initially confused me a bit. Maybe it would be nicer to give the attributes names instead of just numbers? As we keep adding footnotes, that would be less likely to produce conflicts between the different attributes I think.
I'm also adding brian to the cc list, as he first converted this to AsciiDoc for opinions.
In AsciiDoc, footnotes use the named macro syntax. I thought it would be difficult to read to have the footnotes inline, so I chose to use an attribute to substitute them. I used numbers because we had a small number of them and the original footnotes were numbered. I was trying to make a minimal, faithful conversion.
I have no objection to named footnotes and I agree they're easier to use if we have a large number of them. I think whatever we use, we should try to make them unique, as I mentioned above.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
PATCH v2 1/2 SubmittingPatches: replace numbered attributes with names
In reply to Thomas GummererUse names instead of numbers for the AsciiDoc attributes that are used for the footnotes. We will add more footnotes in subsequent commits, and attributes should ideally all be unique. Having named attributes will help ensure uniqueness, and we won't have to re-number the attributes if we add a footnote earlier in the document.
In addition it also clarifies that the attribute name/number is not related to the number the footnote will get in the output.
---
Thanks Junio, Jonathan and brian for the comments on the previous round at <[email protected]>. This round squashes the two patches I sent previously adding the mentions of the security mailing list into one, and adds this preparatory patch.
The security mailing list is now mentioned twice in SubmittingPatches, to make sure people don't miss it, and the wording was adjusted to match the document better.
Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/SubmittingPatches +4 -4
@@ -264,12 +264,12 @@ people who are involved in the area you are touching (the `git contacts` command in `contrib/contacts/` can help to identify them), to solicit comments and reviews. -:1: footnote:[The current maintainer: [email protected]] -:2: footnote:[The mailing list: [email protected]] +:current-maintainer: footnote:[The current maintainer: [email protected]] +:git-ml: footnote:[The mailing list: [email protected]] After the list reached a consensus that it is a good idea to apply the -patch, re-send it with "To:" set to the maintainer{1} and "cc:" the -list{2} for inclusion. +patch, re-send it with "To:" set to the maintainer{current-maintainer} and "cc:" the +list{git-ml} for inclusion. Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and `Tested-by:` lines as necessary to credit people who helped your
Signature · 1 line
2.17.0.1181.g093e983b0
PATCH v2 2/2 note [email protected] in more places
Add a mention of the security mailing list to the README, and to Documentation/SubmittingPatches.. 2caa7b8d27 ("git manpage: note [email protected]", 2018-03-08) already added it to the man page, but for developers either the README, or the documentation on how to contribute (SubmittingPatches) may be the first place to look.
Use the same wording as we already have on the git-scm.com website and in the man page for the README, while the wording is adjusted in SubmittingPatches to match the surrounding document better.
--- Documentation/SubmittingPatches | 13 +++++++++++++ README.md | 3 +++ 2 files changed, 16 insertions(+)
Documentation/SubmittingPatches +13 -0
@@ -176,6 +176,12 @@ that is fine, but please mark it as such. [[send-patches]] === Sending your patches. +:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]] + +Before sending any patches, please note that patches that may be +security relevant should be submitted privately to the Git Security +mailing list{security-ml}, instead of the public mailing list. + Learn to use format-patch and send-email if possible. These commands are optimized for the workflow of sending patches, avoiding many ways your existing e-mail client that is optimized for "multipart/*" mime
@@ -259,6 +265,13 @@ patch, format it as "multipart/signed", not a text/plain message that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is not a text/plain, it's something else. +:security-ml-ref: footnoteref:[security-ml] + +As mentioned at the beginning of the section, patches that may be +security relevant should not be submitted to the public mailing list +mentioned below, but should instead be sent privately to the Git +Security mailing list{security-ml-ref}. + Send your patch with "To:" set to the mailing list, with "cc:" listing people who are involved in the area you are touching (the `git contacts` command in `contrib/contacts/` can help to
README.md +3 -0
@@ -36,6 +36,9 @@ the body to [email protected]. The mailing list archives are available at <https://public-inbox.org/git/>, <http://marc.info/?l=git> and other archival sites. +Issues which are security relevant should be disclosed privately to +the Git Security mailing list <[email protected]>. + The maintainer frequently sends the "What's cooking" reports that list the current status of various development topics to the mailing list. The discussion following them give a good reference for
Signature · 1 line
2.17.0.1181.g093e983b0
Re: [PATCH v2 2/2] note [email protected] in more places
Quoted 35 lines · Thomas Gummerer
Add a mention of the security mailing list to the README, and to
Documentation/SubmittingPatches..2caa7b8d27("git manpage: note [email protected]", 2018-03-08) already added it to the man page, but for developers either the README, or the documentation on how to contribute (SubmittingPatches) may be the first place to look.Use the same wording as we already have on the git-scm.com website and in the man page for the README, while the wording is adjusted in SubmittingPatches to match the surrounding document better.
Signed-off-by Thomas Gummerer <[email protected]>--- Documentation/SubmittingPatches | 13 +++++++++++++ README.md | 3 +++ 2 files changed, 16 insertions(+)Documentation/SubmittingPatches +6
-0@@ -176,6 +176,12 @@ that is fine, but please mark it as such. [[send-patches]] === Sending your patches. +:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]] + +Before sending any patches, please note that patches that may be +security relevant should be submitted privately to the Git Security +mailing list{security-ml}, instead of the public mailing list. + Learn to use format-patch and send-email if possible. These commands are optimized for the workflow of sending patches, avoiding many ways your existing e-mail client that is optimized for "multipart/*" mime
Documentation/SubmittingPatches patch, format it as "multipart/signed", not a text/plain message · line 268
Quoted 4 lines
Documentation/SubmittingPatches +1
-0@@ -259,6 +265,13 @@ patch, format it as "multipart/signed", not a text/plain message that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is not a text/plain, it's something else. +:security-ml-ref: footnoteref:[security-ml]
My only feedback here is that using the footnoteref syntax to refer to the previous footnote potentially makes this a little less readable for plain text users, although it also reduces duplication. I'm not sure I feel strongly one way or the other on this.
Otherwise, this looked fine to me.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Re: [PATCH v2 2/2] note [email protected] in more places
Quoted 39 lines · brian m. carlson
Quoted 38 lines · Thomas Gummerer
Add a mention of the security mailing list to the README, and to
Documentation/SubmittingPatches..2caa7b8d27("git manpage: note [email protected]", 2018-03-08) already added it to the man page, but for developers either the README, or the documentation on how to contribute (SubmittingPatches) may be the first place to look.Use the same wording as we already have on the git-scm.com website and in the man page for the README, while the wording is adjusted in SubmittingPatches to match the surrounding document better.
Signed-off-by Thomas Gummerer <[email protected]>--- Documentation/SubmittingPatches | 13 +++++++++++++ README.md | 3 +++ 2 files changed, 16 insertions(+)Documentation/SubmittingPatches +6
-0@@ -176,6 +176,12 @@ that is fine, but please mark it as such. [[send-patches]] === Sending your patches. +:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]] + +Before sending any patches, please note that patches that may be +security relevant should be submitted privately to the Git Security +mailing list{security-ml}, instead of the public mailing list. + Learn to use format-patch and send-email if possible. These commands are optimized for the workflow of sending patches, avoiding many ways your existing e-mail client that is optimized for "multipart/*" mime@@ -259,6 +265,13 @@ patch, format it as "multipart/signed", not a text/plain message that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is not a text/plain, it's something else.
Quoted 6 lines
Documentation/SubmittingPatches patch, format it as "multipart/signed", not a text/plain message · line 268
Quoted 1 line
Documentation/SubmittingPatches +1
-0+:security-ml-ref: footnoteref:[security-ml]My only feedback here is that using the footnoteref syntax to refer to the previous footnote potentially makes this a little less readable for plain text users, although it also reduces duplication. I'm not sure I feel strongly one way or the other on this.
Yeah, using the plain footnote syntax we end up with two footnotes that are exactly the same, which felt a little awkward. But I don't feel strongly either, so if the consensus is to duplicate the footnote for better readability in plain text I'm happy to change that.
To really improve the readability we'd probably have to duplicate the attribute as well, which I wanted to avoid (altough it's not completely possible with the footnoteref syntax either).
Quoted 4 lines
Otherwise, this looked fine to me.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204