Merge pull request #43054 from github/repo-sync

Repo sync

Author: docs-bot

.github/instructions/style-guide-summary.instructions.md

@@ -0,0 +1,103 @@
+---
+applyTo: "content/**,data/**,**/*.md"
+---
+
+# Concise style guide for docs.github.com
+
+**When to use**: Any content editing, documentation writing, or Markdown file changes. This is a condensed version of the full style guide at `/content/contributing/style-guide-and-content-model/style-guide.md`. Use these rules for routine work. Only consult the full style guide if you encounter a style question not covered here.
+
+For Liquid variable usage, reusables, linking conventions, bullet-list formatting, and parenthetical dashes, see `content.instructions.md` (loaded automatically alongside this file).
+
+## Core principles
+
+1. **Simplicity**: Keep guidelines and content easy to apply. Short paragraphs (1–3 sentences), tables for structured data, bullet lists for sets of items.
+2. **User-first**: Style decisions are based on what's best for the reader, not on grammar rules or stylistic preferences.
+3. **Clarity first**: Prioritize meaning and readability over rigid grammatical rules.
+4. **Use judgment**: When the style guide doesn't cover a case, consider the surrounding content and what the reader needs at that point, then make a decision that fits.
+
+## Voice and tone
+
+* Use clear, simple language approachable for a wide range of readers.
+* Use active voice whenever possible. Passive voice is acceptable when emphasizing the object of an action.
+* Avoid idioms, slang, and region-specific phrases.
+* Avoid ambiguous modal verbs ("may", "might", "should", "could") when an action is required. Use definitive verbs instead.
+* Refer to people as "people" or "users", not "customers."
+
+## Headers
+
+* Use sentence casing for all headers.
+* Headers must start at H2 (`##`). Do not skip header levels (for example, H2 to H4).
+* There must be text content between a header and its first subheader.
+* Each header at the same level on a page must be unique.
+
+## Procedural steps
+
+* Always use numbered lists for procedures.
+* Each step must include an instruction.
+* Give readers all prerequisites before the procedure, not within steps.
+
+## Code blocks
+
+* Keep lines to about 60 characters to avoid horizontal scrolling.
+* Specify the language after the opening code fence (for example, ` ```shell `, ` ```yaml `).
+* Use ALL CAPS for placeholder values that readers must replace (for example, `YOUR-REPOSITORY`). Explain what to replace placeholders with.
+* Do not use command prompts like `$` before commands.
+* If showing command output, comment it out so the command can be copied and run without modification.
+
+## Alerts
+
+* Use alerts sparingly—no consecutive alerts, no more than one per section.
+* Keep alerts concise (a couple of sentences max).
+* Use Markdown syntax: `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!CAUTION]`, `> [!IMPORTANT]`.
+
+## Links
+
+* Use `[AUTOTITLE](/path/to/article)` for all internal links. Never hardcode article titles in link text.
+* Introduce links with "For more information, see" or "See" when context is clear.
+* Do not use inline links where words within a sentence are hyperlinked without additional context.
+* Do not include punctuation inside a hyperlink.
+* Do not repeat the same link more than once in the same article.
+
+## Lists
+
+* Use `*` (asterisks) for unordered lists, never `-` (hyphens).
+* Capitalize the first letter of each list item.
+* Use periods only if the item is a complete sentence.
+* Introduce lists with a descriptive sentence, not vague phrases like "the following" in isolation.
+
+## Tables
+
+* Use tables for tabular data (comparisons, options with multiple attributes). Do not use tables for simple lists.
+* Every cell must contain a value—use "None" or "Not applicable" for empty cells, not "N/A".
+* Left-align text columns. Center-align columns containing only icons.
+
+## Emphasis
+
+* Use **bold** for UI elements that can be interacted with, and for emphasis (sparingly, no more than five contiguous words).
+* Do not bold text that already has other formatting (for example, all-caps placeholders).
+
+## Keyboard shortcuts
+
+* Use `<kbd>` tags for each individual key: `<kbd>Ctrl</kbd>+<kbd>C</kbd>`.
+* Use `+` between key combinations with no spaces.
+* Use full words for Apple modifier keys (`Command`, `Option`, `Control`), not symbols.
+* Capitalize letter keys.
+
+## Product names and variables
+
+* Always use Liquid variables for product names—never hardcode them. Check `data/variables/product.yml` and `data/variables/copilot.yml`.
+* Product names are always singular (for example, "GitHub Actions helps" not "help").
+
+## Word choice
+
+| Use | Avoid |
+|---|---|
+| terminal | shell |
+| sign in | log in, login |
+| sign up | signup |
+| email | e-mail |
+| press (a key) | hit, tap |
+| type (in the UI) | enter (in the UI) |
+| enter (in the command line) | type (in the command line) |
+| repository | repo |
+| administrator | admin |

content/code-security/concepts/vulnerability-reporting-and-management/about-repository-security-advisories.md

@@ -29,9 +29,9 @@ topics:
 
 With repository security advisories, you can:
 
-1. Create a draft security advisory, and use the draft to privately discuss the impact of the vulnerability on your project. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory).
+1. Create a draft security advisory, and use the draft to privately discuss the impact of the vulnerability on your project.
 1. Privately collaborate to fix the vulnerability in a temporary private fork.
-1. Publish the security advisory to alert your community of the vulnerability once a patch is released. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory).
+1. Publish the security advisory to alert your community of the vulnerability once a patch is released.
 
 {% data reusables.repositories.security-advisories-republishing %}
 
@@ -58,8 +58,30 @@ If a security advisory is specifically for npm, we also publish the advisory to
 When you create a security advisory for a public repository on {% data variables.product.prodname_dotcom %}, you have the option of providing an existing CVE identification number for the security vulnerability. {% data reusables.repositories.request-security-advisory-cve-id %}
 
 Once you've published the security advisory and {% data variables.product.prodname_dotcom %} has assigned a CVE identification number to the vulnerability, {% data variables.product.prodname_dotcom %} publishes the CVE to the MITRE database.
-For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory).
 
-## {% data variables.product.prodname_dependabot_alerts %} for published security advisories
+## Publication of security advisories
 
-{% data reusables.repositories.github-reviews-security-advisories %}
+Publishing a security advisory notifies your community about the vulnerability it addresses, making it easier for them to update package dependencies and research the impact of the vulnerability.
+
+When you publish a draft advisory from a public repository, visibility levels vary as follows:
+
+* **Anyone** can see the current version of the advisory data, as well as any advisory credits that the credited users have accepted.
+* **Collaborators** can view the conversation history of the advisory.
+
+The URL of a security advisory does not change after publication.
+
+If you need to update or correct information in a security advisory that you've published, you can edit the security advisory. See [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory).
+
+### {% data variables.product.prodname_dependabot_alerts %} for published security advisories
+
+{% data variables.product.prodname_dotcom %} will review each published security advisory, add it to the {% data variables.product.prodname_advisory_database %}, and may use the security advisory to send {% data variables.product.prodname_dependabot_alerts %} to affected repositories. If the security advisory comes from a fork, we'll only send an alert if the fork owns a package, published under a unique name, on a public package registry. This process can take up to 72 hours and {% data variables.product.prodname_dotcom %} may contact you for more information.
+
+### Importance of fix versions
+
+Whenever possible, you should **add a fix version to a security advisory prior to publishing the advisory**. If you don't, the advisory will be published without a fixed version, and {% data variables.product.prodname_dependabot %} will alert your users about the issue, without offering any safe version to update to.
+
+Depending on the vulnerability, you may need to adjust your approach. If a fix version is:
+
+* **Imminently available**, and you are able to, wait to disclose the issue when the fix is ready.
+* **In development but not yet available**, mention this in the advisory, and edit the advisory later, after publication.
+* **Not planned**, be clear about it in the advisory so that your users don't contact you to ask when a fix will be made. In this case, it is helpful to include steps users can take to mitigate the issue.