From 441d05b64b69dd56d934b0c491bfbf45b5b200aa Mon Sep 17 00:00:00 2001 From: Greta Parks Date: Tue, 18 Apr 2023 08:51:49 -0600 Subject: [PATCH 1/2] improve wording around ipv6 support (#36404) Co-authored-by: Laura Coursen --- ...managing-a-custom-domain-for-your-github-pages-site.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site.md b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site.md index 9e6523a01462..2940eb2070c4 100644 --- a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site.md +++ b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site.md @@ -80,7 +80,7 @@ To set up an apex domain, such as `example.com`, you must configure a custom dom {% data reusables.repositories.sidebar-settings %} {% data reusables.pages.sidebar-pages %} 4. Under "Custom domain", type your custom domain, then click **Save**. If you are publishing your site from a branch, this will create a commit that adds a `CNAME` file to the root of your source branch. If you are publishing your site with a custom {% data variables.product.prodname_actions %} workflow , no `CNAME` file is created. For more information about your publishing source, see "[AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)." -5. Navigate to your DNS provider and create either an `ALIAS`, `ANAME`, or `A` record. You can also create `AAAA` records for IPv6 support. {% data reusables.pages.contact-dns-provider %} +5. Navigate to your DNS provider and create either an `ALIAS`, `ANAME`, or `A` record. You can also create `AAAA` records for IPv6 support. If you're implementing IPv6 support, we highly recommend using an `A` record in addition to your `AAAA` record, due to slow adoption of IPv6 globally. {% data reusables.pages.contact-dns-provider %} - To create an `ALIAS` or `ANAME` record, point your apex domain to the default domain for your site. {% data reusables.pages.default-domain-information %} - To create `A` records, point your apex domain to the IP addresses for {% data variables.product.prodname_pages %}. ```shell @@ -100,7 +100,7 @@ To set up an apex domain, such as `example.com`, you must configure a custom dom {% indented_data_reference reusables.pages.wildcard-dns-warning spaces=3 %} {% data reusables.command_line.open_the_multi_os_terminal %} 6. To confirm that your DNS record configured correctly, use the `dig` command, replacing _EXAMPLE.COM_ with your apex domain. Confirm that the results match the IP addresses for {% data variables.product.prodname_pages %} above. - - For `A` records. + - For `A` records: ```shell $ dig EXAMPLE.COM +noall +answer -t A > EXAMPLE.COM 3600 IN A 185.199.108.153 @@ -108,7 +108,7 @@ To set up an apex domain, such as `example.com`, you must configure a custom dom > EXAMPLE.COM 3600 IN A 185.199.110.153 > EXAMPLE.COM 3600 IN A 185.199.111.153 ``` - - For `AAAA` records. + - For `AAAA` records: ```shell $ dig EXAMPLE.COM +noall +answer -t AAAA > EXAMPLE.COM 3600 IN AAAA 2606:50c0:8000::153 @@ -116,6 +116,8 @@ To set up an apex domain, such as `example.com`, you must configure a custom dom > EXAMPLE.COM 3600 IN AAAA 2606:50c0:8002::153 > EXAMPLE.COM 3600 IN AAAA 2606:50c0:8003::153 ``` + + Remember to also check your `A` record. {% data reusables.pages.build-locally-download-cname %} {% data reusables.pages.enforce-https-custom-domain %} From c8ff667f2329090907e899d2f5f3d3c3c57d6164 Mon Sep 17 00:00:00 2001 From: Matt Pollard Date: Tue, 18 Apr 2023 17:04:28 +0200 Subject: [PATCH 2/2] Describe release notes in content design system (#33584) Co-authored-by: Laura Coursen --- .../release-issue.md | 211 +++++++++++++++++- contributing/content-model.md | 16 ++ contributing/content-style-guide.md | 178 +++++++++++++++ 3 files changed, 396 insertions(+), 9 deletions(-) diff --git a/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md b/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md index 2f6eed55691f..bb57869add9d 100644 --- a/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md +++ b/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md @@ -32,20 +32,213 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng ``` - [ ] Create a placeholder release notes file called `data/release-notes///PLACEHOLDER.yml`. For example `data/release-notes/enterprise-server/3-1/PLACEHOLDER.yml`. Add the following placeholder content to the file: - ``` - date: '2021-05-04' + **Note:** All of the content in this file will be updated when the release notes are created in the megabranch including the filename `PLACEHOLDER.yml`. You can update the date or leave it as-is and wait to update it when the release notes are finalized. + +
Click to view placeholder... + + ```yaml + date: '2099-12-31' release_candidate: true deprecated: false - intro: PLACEHOLDER + intro: | + {% note %} + + **Note:** If {% data variables.location.product_location %} is running a release candidate build, you can’t upgrade with a hotpatch. We recommend that you only run release candidates in a test environment. + + {% endnote %} + + For upgrade instructions, see "[Upgrading {% data variables.product.prodname_ghe_server %}](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server)." sections: - bugs: - - PLACEHOLDER - known_issues: - - PLACEHOLDER - ``` + # Remove section heading if the section contains no notes. - **Note:** All of the content in this file will be updated when the release notes are created in the megabranch including the filename `PLACEHOLDER.yml`. You can update the date or leave it as-is and wait to update it when the release notes are finalized. + features: + # Remove a sub-section heading if the heading contains no notes. If sections + # that regularly recur are missing, add placeholders to this template. + + - heading: Instance administration + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Instance services + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Identity and access management + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Authentication + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Migrations + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Policies + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Audit logs + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: GitHub Connect + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: GitHub Advanced Security + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Dependabot + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Code security + notes: + # LINK TO RELEASE ISSUE + - | + ... + - heading: GitHub Actions + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: GitHub Packages + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: GitHub Pages + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Community experience + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Organizations + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Repositories + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Issues + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Projects + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: GitHub Discussions + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Commits + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Pull requests + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Releases + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Gist + notes: + # LINK TO RELEASES ISSUE + - | + ... + + - heading: Markdown + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Accessibility + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: GitHub Mobile + notes: + # LINK TO RELEASE ISSUE + - | + ... + + - heading: Integrations and extensions + notes: + # LINK TO RELEASE ISSUE + - | + ... + + changes: + # LINK TO RELEASE ISSUE + - | + ... + + known_issues: + # INCLUDE NOTES FOR RELEASE FROM "GHES Release Note Tracking" PROJECT'S "Known Issues" TAB + - | + ... + + deprecations: + # LINK TO RELEASE ISSUE + - | + ... + ``` +
- [ ] If this is a release candidate release, add a Release Candidate banner: ``` diff --git a/contributing/content-model.md b/contributing/content-model.md index fe78890c2744..9a8388b6dbce 100644 --- a/contributing/content-model.md +++ b/contributing/content-model.md @@ -284,6 +284,22 @@ Use the [procedural content template](https://github.com/github/docs/blob/main/c - [Inviting people to manage your enterprise account](https://docs.github.com/en/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise) - [Setting up continuous integration using workflow templates](https://docs.github.com/en/actions/guides/setting-up-continuous-integration-using-workflow-templates) +### Release notes + +Release notes enable readers to understand and prepare for the customer-facing changes in each release of GitHub's versioned enterprise products (e.g., GitHub Enterprise Server). Good release notes provide administrators the necessary information to plan system upgrades in environments that require change control, and support end users who want to understand and prepare to use new GitHub features and functionality. + +Writers source, edit, and publish release notes in collaboration with product DRIs, feature owners, and individual engineers at GitHub. For each individual release, we group release notes by predefined types. + +We publish the release notes for [GitHub Enterprise Server](https://docs.github.com/enterprise-server/admin/release-notes) (GHES) and [GitHub AE](https://docs.github.com/github-ae@latest/admin/release-notes) (GHAE) on GitHub Docs, in the "Enterprise administrators" documentation set. + +#### Types of releases + +GitHub Docs provides release notes for feature releases of GHES and GHAE, and for patch releases of GHES. For more information about releases of each product, see "About upgrades to new releases" in the [GHES](https://docs.github.com/enterprise-server/admin/overview/about-upgrades-to-new-releases) or [GHAE](https://docs.github.com/github-ae@latest/admin/overview/about-upgrades-to-new-releases) documentation. + +#### Guidance and example release notes + +You can find guidance for the format, style, and tone of release notes, as well as examples of each type of note, in the [Content style guide for GitHub Docs](https://github.com/github/docs/blob/main/contributing/content-style-guide.md#release-notes). + ### Troubleshooting Troubleshooting content includes built-in errors we expect users to encounter, common problems reported to support, and situations people might encounter while completing tasks. Use troubleshooting sections in guides or procedural articles to keep solutions close to procedures. Work with support and product managers to surface common errors and include them in the documentation. diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md index f46fb8204de5..6464b506ecaa 100644 --- a/contributing/content-style-guide.md +++ b/contributing/content-style-guide.md @@ -603,6 +603,184 @@ For more information about GitHub's personal access tokens, see "[Creating a per Follow standard American English punctuation rules. For more guidance, see “[Punctuation](https://docs.microsoft.com/style-guide/punctuation)” in the Microsoft Style Guide. +## Release notes + +A set of release notes on GitHub Docs tell readers about administrator- or user-facing changes to a versioned release of a product like GitHub Enterprise Server (GHES). Release notes appear in the [Enterprise administrator docs](https://docs.github.com/en/enterprise-server/admin/release-notes). + +A good release note is a few sentences that sequentially answer the reader's questions about the change. For more information, see [Content model for GitHub Docs](/contributing/content-model.md#release-notes). + +Each release note in a set describes one of the following changes. + +- [Features](#features): brand-new behavior or functionality +- [Security fixes](#security-fixes): fixes to flaws or unexpected behavior that have security implications +- [Bug fixes](#bug-fixes): fixes to flaws or unexpected behavior +- [Changes](#changes): notable changes to past behavior +- [Deprecations](#deprecations): removal of a feature or behavior + +You can also review guidelines for updating release notes in [Adding or updating a release note](#adding-or-updating-a-release-note). + +### Features + +A release note for a feature summarizes brand-new behavior. Generally, notes for features are only part of feature releases. + +#### Writing release notes for features + +A release note for a feature answers the following questions. + +1. Does this new functionality apply to me, with my role or access? +1. What need does the functionality satisfy? +1. What is the functionality? +1. If applicable, where can I read more about the functionality? + +> _AUDIENCE_ (**1**) can _DESCRIPTION OF NEED_ (**2**) by _DESCRIPTION OF FEATURE'S USE_ (**3**). For more information, see "[_ARTICLE TITLE_]()" (**4**). + +- Categorize each feature in a section, under a feature heading. +- Write in the present tense. +- To reduce repetition and unnecessary words, "now" is usually implied. +- To clarify actors and impact, avoid passive language when possible. + +#### Examples of feature release notes + +- > Site administrators can increase the security of the Management Console by configuring the rate limit for sign-in attempts, as well as the lockout duration after exceeding the rate limit. For more information, see "[Configuring rate limits](https://docs.github.com/enterprise-server@3.7/admin/configuration/configuring-your-enterprise/configuring-rate-limits#configuring-rate-limits-for-authentication-to-the-management-console)." + +- > Enterprise owners can control where users can fork repositories. Forking can be limited to preset combinations of organizations, the same organization as the parent repository, user accounts, or everywhere. For more information, see "[Enforcing repository management policies in your enterprise](https://docs.github.com/enterprise-server@3.7/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-forking-private-or-internal-repositories)." + +- > Users can create files with geoJSON, topoJSON, and STL diagrams and render the diagrams in the web interface. For more information, see "[Working with non-code files](https://docs.github.com/enterprise-server@3.7/repositories/working-with-files/using-files/working-with-non-code-files)." + +### Security fixes + +A release note for a security fix summarizes a change that mitigates or prevents exploitation of a security-related issue in the product. Generally, notes for security fixes are only part of patch releases. + +#### Writing release notes for security fixes + +A release note for a security fix answers the following questions. + +1. If available, what is the [NVD vulnerability severity rating](https://nvd.nist.gov/vuln-metrics/cvss) for the vulnerability that's fixed? +1. What is the attack that an attacker could accomplish by exploiting the vulnerability? +1. What type of vulnerability is exploitable? +1. If available, what is the vulnerability's [CVE identifier](https://cve.mitre.org/cve/identifiers/), pending or active? +1. Did someone report the vulnerability via the [GitHub Bug Bounty program](https://bounty.github.com)? + +> _SEVERITY_ (**1**): An attacker could _DESCRIPTION OF IMPACT_ (**2**) by _DESCRIPTION OF EXPLOIT_ (**3**). GitHub has requested CVE ID [_CVE-####-#####_]() (**4**) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com) (**5**). + +#### Examples of release notes for security fixes + +- > **MEDIUM**: An attacker could cause unbounded resource exhaustion on the instance by making parallel requests to the Markdown REST API. To mitigate this issue, GitHub has updated [CommonMarker](https://github.com/gjtorikian/commonmarker). GitHub has requested CVE ID [CVE-2022-39209](https://nvd.nist.gov/vuln/detail/CVE-2022-39209) for this vulnerability. + +- > **MEDIUM**: An attacker could embed dangerous links in the instance's web UI because pull request preview links did not properly sanitize URLs. This vulnerability was reported via the [GitHub Bug Bounty program](https://bounty.github.com). + +### Bug fixes + +A release note for a bug fix describes a correction to an undesired or otherwise unexpected behavior. Generally, notes for bug fixes are only part of patch releases. + +#### Writing release notes for bug fixes + +A release note for a bug fix answers the following questions. + +1. Did the behavior affect me, with my role or access? +1. What behavior would the reader experience prior to the fix? + +> _AUDIENCE_ (**1**) _DESCRIPTION OF BEHAVIOR_ (**2**). + +- Because the bug is now fixed, write in the past tense. +- To reduce repetition and unnecessary words, language like +- To reduce repetition and unnecessary words, "now" is usually implied. +- To clarify actors and impact, avoid passive language when possible. + +#### Examples of release notes for bug fixes + +- > After a user imported a repository with push protection enabled, the repository was not immediately visible in the security overview's "Security Coverage" view. + +- > On an instance with GitHub Actions enabled, a workflow job for GitHub Actions would not start if a matching runner group was unavailable when the job was initially queued, even if a matching runner group became available after the job entered the queue. + +- > Commands that site administrators ran via SSH on any of the instances nodes were not logged in ``/var/log/ssh-console-audit.log``. + +### Changes + +A release note for a change describes a notable, but minor change to existing behavior. Notes for changes answer the following questions. + +#### Writing release notes for changes + +A release note for a change answers the following questions. + +1. Did the behavior affect me, with my role or access? +1. If the change solves or avoids a problem, what's that problem? +1. What's the new behavior? +1. If relevant, what was the behavior before the change? + +> _AUDIENCE_ (**1**) / _DESCRIPTION OF PROBLEM CHANGE SOLVES_ (**2**) _DESCRIPTION OF NEW BEHAVIOR_ (**3**) _DESCRIPTION OF OLD BEHAVIOR_ (**4**). + +- Because the change applies to the release in question, write notes for changes in the present tense. +- To reduce repetition and unnecessary words, "now" is usually implied. +- To clarify actors and impact, avoid passive language when possible. +- Often, the audience is implied. +- If useful, include relevant links to GitHub Docs. + +#### Examples of release notes for changes + +- > On an instance with a GitHub Advanced Security license, users who author custom patterns for secret scanning can provide expressions that must or must not match that are up to 2,000 characters. This limit is an increase from 1,000 characters. + +- > For administrators who need to review or modify SAML mappings, the default path for output from `ghe-saml-mapping-csv -d` is `/data/user/tmp` instead of `/tmp`. For more information, see "[Command-line utilities](https://docs.github.com/en/enterprise-server@3.8/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-saml-mapping-csv)." + +- > To avoid intermittent issues with the success of Git operations on an instance with multiple nodes, GitHub Enterprise Server checks the status of the MySQL container before attempting a SQL query. The timeout duration has also been reduced. + +### Known issues + +A release note for a known issue describes an issue that GitHub has identified, but cannot or has not yet prioritized. + +#### Writing release notes for known issues + +A release note for a known issue answers the following questions. + +1. Does the behavior affect me, with my role or access? +1. If the change solves or avoids a problem, what's that problem? +1. What are any error messages or other recognizable UI elements that appear? +1. Do I need to act? If so, what should I do? + +> _AUDIENCE_ (**1**) _DESCRIPTION OF ISSUE_ (**2**) _DETAILS OF BEHAVIOR_ (**3**) _NEXT STEPS_ (**4**). + +- To clarify actors and impact, avoid passive language when possible.sent tense. +- To reduce repetition and unnecessary words, "now" is usually implied. +- To clarify actors and impact, avoid passive language when possible. +- If useful, include relevant links to GitHub Docs. +- Known issues are also a [type of content on GitHub Docs](/contributing/content-model.md#known-issues). If useful, write or link to more in-depth and contextually relevant content in the docs. + +#### Examples of release notes for known issues + +- > After a user enables the option for a repository to allow users with read access to create discussions, the feature is not enabled. + +- > After an administrator begins a configuration run, a `No such object error` may occur during the validation phase for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. + +### Deprecations + +A deprecation release note summarizes a behavior or feature that GitHub has removed or plans to remove. Generally, notes for deprecations are only part of feature releases. + +#### Writing release notes for deprecations + +A release note for a deprecation answers the following questions. + +1. Does this existing functionality apply to me, with my role or access? +1. What is the functionality that's being deprecated? +1. If applicable, what replaces the deprecated functionality? +1. If applicable, where can I read more? + +> _AUDIENCE_ (**1**) _DESCRIPTION OF DEPRECATED FUNCTIONALITY_ (**2**) _REPLACEMENT FUNCTIONALITY_ (**3**) For more information, see "[_ARTICLE TITLE_]()" (**4**). + +- Notes are in the present tense, or the future tense for upcoming changes. If applicable, specify the upcoming release where the deprecation will occur. +- To reduce repetition and unnecessary words, "now" is usually implied. +- To clarify actors and impact, avoid passive language when possible. +- Categorize each feature in a section, under a feature heading. + +#### Examples of release notes for deprecations + +- > **Upcoming deprecation**: In GitHub Enterprise Server 3.8 and later, to ensure instance security, unsecure algorithms will be disabled for SSH connections to the administrative shell. + +- > Commit comments, which are comments that users add directly to a commit outside of a pull request, no longer appear in the pull request timeline. Users could not reply to or resolve these comments. The Timeline events REST API and the GraphQL API's `PullRequest` object also no longer return commit comments. + +### Adding or updating a release note + +If you add or update an individual release note after initial publication, to signal to readers that the note has changed, append a datestamp in the format "[Updated: YYYY-MM-DD]". + ## Reusables and variables Use reusable strings for individual nouns (e.g. product names) or for complete sentences or paragraphs. Sentence fragments and phrases should not be contained in reusable strings as they can cause problems when content is localized. For more information, see the [data directory](../data) in the github/docs repository and the “[Product names](#product-names)” section of this document.