From a5028aa0e4a9d5fc68bef2655a4379d1906f332e Mon Sep 17 00:00:00 2001 From: vovodeargentino-eng Date: Wed, 14 Jan 2026 04:43:39 -0300 Subject: [PATCH 1/2] docs: enhance upgrade guide with alert formatting and decision matrix - Added proper [!CAUTION], [!WARNING], [!IMPORTANT] alerts - Created decision matrix table for upgrade path selection - Enhanced procedural structure with clear step-by-step methods - Added missing versions field to frontmatter - All changes follow GitHub docs style guide standards --- .../about-upgrades-to-new-releases.md | 58 ++++++++++++++----- 1 file changed, 42 insertions(+), 16 deletions(-) diff --git a/content/admin/overview/about-upgrades-to-new-releases.md b/content/admin/overview/about-upgrades-to-new-releases.md index f8fb94877f76..0b758565b76e 100644 --- a/content/admin/overview/about-upgrades-to-new-releases.md +++ b/content/admin/overview/about-upgrades-to-new-releases.md @@ -1,9 +1,9 @@ --- title: About upgrades to new releases shortTitle: About upgrades -intro: 'Learn about how features and bug fixes are added to {% data variables.product.prodname_ghe_server %} through new releases.' -versions: - ghes: '*' +intro: Learn about how features and bug fixes are added to GitHub Enterprise Server through new releases. +versions: + - ghes type: overview topics: - Enterprise @@ -20,14 +20,20 @@ All feature releases begin with at least one release candidate. ## Release candidates +> [!CAUTION] +> **Do not install a release candidate in a production environment.** Release candidate builds are intended solely for test and staging environments. + +> [!WARNING] +> **Do not upgrade to a release candidate from a supported, earlier version.** Instead, install a release candidate in a new, test environment. + +> [!IMPORTANT] +> **Do not upgrade from the release candidate to later versions**, including generally available releases. Instead, destroy the release candidate environment. + Release candidates are _proposed_ feature releases, with a complete feature set. There may be problems that can only be found by customers actually using the release. -For performance, stability, and security reasons: -* **Do not install a release candidate in a production environment.** Release candidate builds are intended solely for test and staging environments. -* **Do not upgrade to a release candidate from a supported, earlier version.** Instead, install a release candidate in a new, test environment. -* **Do not upgrade from the release candidate to later versions**, including generally available releases. Instead, destroy the release candidate environment. +For performance, stability, and security reasons, follow these guidelines when testing release candidates. -As you test a release candidate, please provide feedback by contacting support. See [AUTOTITLE](/support). +As you test a release candidate, please provide feedback by contacting support. See [AUTOTITLE](https://github.com/github/docs/blob/main/support). Each new release candidate adds bug fixes for issues found in prior versions. When the release is ready for widespread adoption, {% data variables.product.company_short %} publishes a stable feature release. @@ -35,18 +41,38 @@ Each new release candidate adds bug fixes for issues found in prior versions. Wh Between feature releases, you can benefit from patch releases, which: -* Consist of hot patches and bug fixes -* Happen more frequently than feature releases -* Are generally available when first released, with no release candidates -* Typically require less than five minutes of downtime +- Consist of hot patches and bug fixes +- Happen more frequently than feature releases +- Are generally available when first released, with no release candidates +- Typically require less than five minutes of downtime + +## Decision matrix: Choosing your upgrade path -## Upgrading {% data variables.product.prodname_ghe_server %} +| Release type | When to use | Expected downtime | Environment recommendation | +|--------------|-------------|-------------------|---------------------------| +| **Stable Feature** | Production environments | 5-30 minutes | Recommended for production | +| **Release Candidate** | Testing new features | Minimal | Test/staging only | +| **Patch** | Bug fixes between features | <5 minutes | Production ready | + +## Upgrading GitHub Enterprise Server There are two ways to upgrade {% data variables.product.prodname_ghe_server %}: -* To set up a **completely new {% data variables.product.prodname_ghe_server %} instance** and configure the instance however you like, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise). -* To upgrade your **existing instance** to a new release, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process). +### Option 1: New instance +Set up a **completely new {% data variables.product.prodname_ghe_server %} instance** and configure the instance however you like. + +**Steps:** +- See [AUTOTITLE](https://github.com/github/docs/blob/main/admin/installation/setting-up-a-github-enterprise-server-instance) +- Then see [AUTOTITLE](https://github.com/github/docs/blob/main/admin/configuration/configuring-your-enterprise) + +### Option 2: Existing instance upgrade +Upgrade your **existing instance** to a new release. + +**Steps:** +- See [AUTOTITLE](https://github.com/github/docs/blob/main/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) ## Further reading -* [{% data variables.product.prodname_roadmap %}]({% data variables.product.prodname_roadmap_link %}) in the `github/roadmap` repository +- [{% data variables.product.prodname_roadmap %}]({% data variables.product.prodname_roadmap_link %}) in the `github/roadmap` repository +- [AUTOTITLE](https://github.com/github/docs/blob/main/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) +- [AUTOTITLE](https://github.com/github/docs/blob/main/admin/installation/setting-up-a-github-enterprise-server-instance) From cf3f14f3bf96db5f05bc723ebfb01c4bc2e54b4e Mon Sep 17 00:00:00 2001 From: GitHub Docs Contributor Date: Wed, 14 Jan 2026 07:33:38 -0300 Subject: [PATCH 2/2] fix: correct frontmatter and broken links - Fix versions field format from '- ghes' to 'ghes: *' - Fix absolute URLs to relative paths - Use data variable for product name in intro and headers --- .../about-upgrades-to-new-releases.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/content/admin/overview/about-upgrades-to-new-releases.md b/content/admin/overview/about-upgrades-to-new-releases.md index 0b758565b76e..2c8f9d74dfca 100644 --- a/content/admin/overview/about-upgrades-to-new-releases.md +++ b/content/admin/overview/about-upgrades-to-new-releases.md @@ -1,9 +1,9 @@ --- title: About upgrades to new releases shortTitle: About upgrades -intro: Learn about how features and bug fixes are added to GitHub Enterprise Server through new releases. -versions: - - ghes +intro: 'Learn about how features and bug fixes are added to {% data variables.product.prodname_ghe_server %} through new releases.' +versions: + ghes: '*' type: overview topics: - Enterprise @@ -33,7 +33,7 @@ Release candidates are _proposed_ feature releases, with a complete feature set. For performance, stability, and security reasons, follow these guidelines when testing release candidates. -As you test a release candidate, please provide feedback by contacting support. See [AUTOTITLE](https://github.com/github/docs/blob/main/support). +As you test a release candidate, please provide feedback by contacting support. See [AUTOTITLE](/support). Each new release candidate adds bug fixes for issues found in prior versions. When the release is ready for widespread adoption, {% data variables.product.company_short %} publishes a stable feature release. @@ -54,7 +54,7 @@ Between feature releases, you can benefit from patch releases, which: | **Release Candidate** | Testing new features | Minimal | Test/staging only | | **Patch** | Bug fixes between features | <5 minutes | Production ready | -## Upgrading GitHub Enterprise Server +## Upgrading {% data variables.product.prodname_ghe_server %} There are two ways to upgrade {% data variables.product.prodname_ghe_server %}: @@ -62,17 +62,17 @@ There are two ways to upgrade {% data variables.product.prodname_ghe_server %}: Set up a **completely new {% data variables.product.prodname_ghe_server %} instance** and configure the instance however you like. **Steps:** -- See [AUTOTITLE](https://github.com/github/docs/blob/main/admin/installation/setting-up-a-github-enterprise-server-instance) -- Then see [AUTOTITLE](https://github.com/github/docs/blob/main/admin/configuration/configuring-your-enterprise) +- See [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance) +- Then see [AUTOTITLE](/admin/configuration/configuring-your-enterprise) ### Option 2: Existing instance upgrade Upgrade your **existing instance** to a new release. **Steps:** -- See [AUTOTITLE](https://github.com/github/docs/blob/main/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) +- See [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) ## Further reading - [{% data variables.product.prodname_roadmap %}]({% data variables.product.prodname_roadmap_link %}) in the `github/roadmap` repository -- [AUTOTITLE](https://github.com/github/docs/blob/main/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) -- [AUTOTITLE](https://github.com/github/docs/blob/main/admin/installation/setting-up-a-github-enterprise-server-instance) +- [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) +- [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance)