Reorder sections to make it more clear to the reader that requesting a CVE number is optional #10210

darakian · 2021-09-21T18:32:38Z

At the moment the publication doc leads with the topic of requesting a CVE number.
This PR moves things around and adds language to imply that a CVE number is not required in order to publish a GHSA.
The impetus for this PR comes from an out of band conversation with the rustsec community and some confusion around GHSA publication.

Why:

Closes #10209

What's being changed:

Minor reordering of sections and more additional language.

Check off the following:

I have reviewed my changes in staging (look for the latest deployment event in your pull request's timeline, then click View deployment).
For content changes, I have completed the self-review checklist.

Writer impact (This section is for GitHub staff members only):

This pull request impacts the contribution experience
- I have added the 'writer impact' label
- I have added a description and/or a video demo of the changes below (e.g. a "before and after video")

…a CVE number is optional At the moment the publication doc leads with the topic of requesting a CVE number. This PR moves things around and adds language to imply that a CVE number is not required in order to publish a GHSA. The impetus for this PR comes from an out of band conversation with the rustsec community and some confusion around GHSA publication.

welcome · 2021-09-21T18:32:39Z

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

rschultheis

This is awesome, I left one suggestion though it might be a bit wordy. I think this PR could go out as is. Thanks @darakian

content/code-security/security-advisories/publishing-a-security-advisory.md

…y-advisory.md Co-authored-by: Robert Schultheis <rschultheis@github.com>

ramyaparimi · 2021-09-22T13:44:03Z

@darakian
Thanks so much for opening a PR! I'll get this triaged for review ⚡

lucascosti · 2021-09-23T06:25:34Z

content/code-security/security-advisories/publishing-a-security-advisory.md

@@ -92,6 +76,22 @@ Publishing a security advisory deletes the temporary private fork for the securi

 {% data reusables.repositories.github-reviews-security-advisories %}

+## Requesting a CVE identification number (Optional)
+
+Github can provide a CVE number if needed and if the software is not under the scope of another CVE Numbering Authority (CNA). Anyone with admin permissions to a security advisory can request a CVE identification number for the security advisory. If the advisory already has a CVE number, then that can be input in the advisory form.


👋 @darakian, thanks heaps for this PR! I agree that if the step is optional, then it should be moved lower and marked as such.

🤔 Most of the added content in this paragraph is already provided in the next paragraph in the {% data reusables.repositories.request-security-advisory-cve-id %} reusable. You can see the content of that resuable file here. You can see a built stage of this branch here.

I would recommend sticking with the current wording in the reusable, or modifying the reusable directly.

Suggested change

Github can provide a CVE number if needed and if the software is not under the scope of another CVE Numbering Authority (CNA). Anyone with admin permissions to a security advisory can request a CVE identification number for the security advisory. If the advisory already has a CVE number, then that can be input in the advisory form.

Anyone with admin permissions to a security advisory can request a CVE identification number for the security advisory.

Thanks for the tip. I was unaware of what those {%...%} patterns were. I've pushed a commit which removes the leading text from the base doc and alters the reusable. Let me know what you think @lucascosti

@rschultheis can I get a second review on the updated content?

rschultheis

this all looks good to me, though I defer to @lucascosti and docs team in general. I think this does make it more clear that a CVE is optional which is the goal.

removed duplicate line on short titles

lucascosti

Thanks, @darakian! I've added a few wording suggestions.

🤔 I'm also having second thoughts about moving the "Requesting a CVE identification number" section below the "Publishing" one. If someone wants to have a CVE, does a CVE need to be assigned before an advisory is published?

If so, we'd probably want the articles and sections to be in the order of the workflow. e.g. Draft -> request CVE -> publish.

I think adding the (Optional) to the section title now clearly indicates that it is not required to publish an advisory.

data/reusables/repositories/request-security-advisory-cve-id.md

Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com>

darakian · 2021-09-24T15:33:45Z

does a CVE need to be assigned before an advisory is published?

No. A CVE can be requested for the advisory either during the initial advisory publication step or later on.

I've added a few wording suggestions.

Those look good to me 👍

lucascosti

No. A CVE can be requested for the advisory either during the initial advisory publication step or later on.

Awesome, thanks for confirming! I'll merge this in 🚀

…re-clearly-optional

github-actions · 2021-09-27T01:15:00Z

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours. If you're looking for your next contribution, check out our help wanted issues ⚡

darakian requested a review from rschultheis September 21, 2021 18:32

github-actions bot added the triage Do not begin working on this issue until triaged by the team label Sep 21, 2021

rschultheis previously approved these changes Sep 21, 2021

View reviewed changes

content/code-security/security-advisories/publishing-a-security-advisory.md Outdated Show resolved Hide resolved

Update content/code-security/security-advisories/publishing-a-securit…

3acad38

…y-advisory.md Co-authored-by: Robert Schultheis <rschultheis@github.com>

darakian dismissed rschultheis’s stale review via 3acad38 September 21, 2021 20:18

Add 'if' for clarity

d1049f1

ramyaparimi added content This issue or pull request belongs to the Docs Content team waiting for review Issue/PR is waiting for a writer's review and removed triage Do not begin working on this issue until triaged by the team labels Sep 22, 2021

lucascosti reviewed Sep 23, 2021

View reviewed changes

Remove leading text and make edits in the 'reusable'

4f7584e

darakian requested a review from rschultheis September 23, 2021 15:35

rschultheis previously approved these changes Sep 23, 2021

View reviewed changes

ghost referenced this pull request Sep 24, 2021

Update content-style-guide.md

b2e195c

removed duplicate line on short titles

lucascosti reviewed Sep 24, 2021

View reviewed changes

data/reusables/repositories/request-security-advisory-cve-id.md Outdated Show resolved Hide resolved

data/reusables/repositories/request-security-advisory-cve-id.md Outdated Show resolved Hide resolved

Update data/reusables/repositories/request-security-advisory-cve-id.md

d90a009

Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com>

darakian dismissed rschultheis’s stale review via d90a009 September 24, 2021 15:33

Update data/reusables/repositories/request-security-advisory-cve-id.md

3dde915

Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com>

lucascosti approved these changes Sep 27, 2021

View reviewed changes

Merge branch 'main' into reorder-advisory-publication-doc-make-cve-mo…

aacec78

…re-clearly-optional

lucascosti enabled auto-merge (squash) September 27, 2021 01:05

lucascosti merged commit 9a491b2 into main Sep 27, 2021

lucascosti deleted the reorder-advisory-publication-doc-make-cve-more-clearly-optional branch September 27, 2021 01:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorder sections to make it more clear to the reader that requesting a CVE number is optional #10210

Reorder sections to make it more clear to the reader that requesting a CVE number is optional #10210

darakian commented Sep 21, 2021 •

edited

Loading

welcome bot commented Sep 21, 2021

rschultheis left a comment

ramyaparimi commented Sep 22, 2021

lucascosti Sep 23, 2021

darakian Sep 23, 2021

rschultheis left a comment

lucascosti left a comment

darakian commented Sep 24, 2021

lucascosti left a comment

github-actions bot commented Sep 27, 2021

	Github can provide a CVE number if needed and if the software is not under the scope of another CVE Numbering Authority (CNA). Anyone with admin permissions to a security advisory can request a CVE identification number for the security advisory. If the advisory already has a CVE number, then that can be input in the advisory form.
	Anyone with admin permissions to a security advisory can request a CVE identification number for the security advisory.

Reorder sections to make it more clear to the reader that requesting a CVE number is optional #10210

Reorder sections to make it more clear to the reader that requesting a CVE number is optional #10210

Conversation

darakian commented Sep 21, 2021 • edited Loading

Why:

What's being changed:

Check off the following:

Writer impact (This section is for GitHub staff members only):

welcome bot commented Sep 21, 2021

rschultheis left a comment

Choose a reason for hiding this comment

ramyaparimi commented Sep 22, 2021

lucascosti Sep 23, 2021

Choose a reason for hiding this comment

darakian Sep 23, 2021

Choose a reason for hiding this comment

rschultheis left a comment

Choose a reason for hiding this comment

lucascosti left a comment

Choose a reason for hiding this comment

darakian commented Sep 24, 2021

lucascosti left a comment

Choose a reason for hiding this comment

github-actions bot commented Sep 27, 2021

darakian commented Sep 21, 2021 •

edited

Loading