Merge pull request #41872 from github/repo-sync

Repo sync

Author: docs-bot

content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics.md

@@ -15,8 +15,12 @@ shortTitle: OpenTelemetry metrics
 
 {% data reusables.enterprise.opentelemetry-migration %}
 
+{% ifversion ghes = 3.18 %}
+
 {% data reusables.enterprise.opentelemetry-preview %}
 
+{% endif %}
+
 ## About OpenTelemetry metrics
 
 The OpenTelemetry monitoring stack is based on industry-standard observability tools and includes various components for collecting, processing, and storing metrics. This comprehensive approach provides a complete view of your system's performance and health across all components of your {% data variables.product.prodname_ghe_server %} instance.

content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md

@@ -15,8 +15,12 @@ shortTitle: Configure OpenTelemetry
 
 {% data reusables.enterprise.opentelemetry-migration %}
 
+{% ifversion ghes = 3.18 %}
+
 {% data reusables.enterprise.opentelemetry-preview %}
 
+{% endif %}
+
 ## Prerequisites
 
 * {% data variables.product.prodname_ghe_server %} 3.18 or later
@@ -25,6 +29,12 @@ shortTitle: Configure OpenTelemetry
 
 ## Enabling OpenTelemetry metrics
 
+{% ifversion ghes > 3.18 %}
+
+OpenTelemetry metrics are enabled by default for **new installations** of {% data variables.product.prodname_ghe_server %} 3.19 and later. Upgrades to {% data variables.product.prodname_ghe_server %} 3.19 will still have `collectd` metrics enabled by default, but you can choose to switch to OpenTelemetry metrics.
+
+{% else %}
+
 OpenTelemetry metrics are disabled by default. You can enable them through the {% data variables.enterprise.management_console %} or command line.
 
 ### Using the {% data variables.enterprise.management_console %}
@@ -47,6 +57,8 @@ OpenTelemetry metrics are disabled by default. You can enable them through the {
 
 {% data reusables.enterprise.apply-configuration %}
 
+{% endif %}
+
 ## Performance considerations
 
 When configuring OpenTelemetry metrics, consider the following performance factors:

content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/enable-advanced-dashboards.md

@@ -15,8 +15,12 @@ shortTitle: Enable advanced dashboards
 
 {% data reusables.enterprise.opentelemetry-migration %}
 
+{% ifversion ghes = 3.18 %}
+
 {% data reusables.enterprise.opentelemetry-preview %}
 
+{% endif %}
+
 ## Additional dashboards
 
 When OpenTelemetry metrics are enabled, you can turn on advanced Grafana dashboards with enhanced visualization and monitoring capabilities.

content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md

@@ -15,4 +15,8 @@ shortTitle: OpenTelemetry metrics
 
 {% data reusables.enterprise.opentelemetry-migration %}
 
+{% ifversion ghes = 3.18 %}
+
 {% data reusables.enterprise.opentelemetry-preview %}
+
+{% endif %}

content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/setting-up-external-monitoring-with-opentelemetry.md

@@ -13,8 +13,12 @@ type: how_to
 shortTitle: External monitoring OpenTelemetry
 ---
 
+{% ifversion ghes = 3.18 %}
+
 {% data reusables.enterprise.opentelemetry-preview %}
 
+{% endif %}
+
 ## External monitoring approaches
 
 External monitoring with OpenTelemetry allows you to integrate your {% data variables.product.prodname_ghe_server %} instance with existing monitoring infrastructure and tools. {% data variables.product.prodname_ghe_server %} provides two primary approaches for external monitoring:
@@ -126,7 +130,7 @@ scrape_configs:
     scheme: https
     tls_config:
       # Set `true` only when testing with self-signed certificates
-      insecure_skip_verify: false  
+      insecure_skip_verify: false
 ```
 
 #### Other monitoring tools

src/links/README.md

@@ -1,3 +1,79 @@
 # Links
 
-This subject folder contains files that support link features on docs.github.com, such as hover card, auto generated links, and updating links for different versions and languages.
+This module contains the tooling and components responsible for link integrity, user experience (hover previews), and maintenance across the GitHub Docs site.
+
+## Purpose & Scope
+
+The `src/links` directory manages:
+- **Link Validation**: Ensuring all internal and external links in the documentation are valid.
+- **Link Maintenance**: Automated tools to update links when pages are moved or renamed.
+- **User Experience**: Components like "Hover Cards" that provide context when users hover over internal links.
+- **Compliance**: Checking for specific link patterns (e.g., `github/github` links).
+
+## Architecture
+
+### Components
+
+- **`LinkPreviewPopover.tsx`**: A React component that renders a preview card when a user hovers over a link. It handles:
+  - **Delay Logic**: Prevents the popover from appearing during accidental mouse-overs.
+  - **Positioning**: Ensures the popover appears near the link without going off-screen.
+
+### Libraries (`src/links/lib`)
+
+- **`update-internal-links.ts`**: The core logic for refactoring links. It parses Markdown/Liquid, identifies links, and updates their `href` or title based on a provided map of changes. It handles:
+  - Stripping Liquid conditionals to find the "pure" link.
+  - Updating frontmatter links.
+  - Handling anchors and query parameters.
+- **`excluded-links.ts`**: Configuration for links that should be ignored by validators (e.g., localhost links, specific example domains).
+
+### Scripts (`src/links/scripts`)
+
+- **`rendered-content-link-checker.ts`**: A comprehensive CLI tool that:
+  - Renders content pages to HTML.
+  - Parses the HTML to find all `<a>` and `<img>` tags.
+  - Validates internal links (checking for 404s, broken anchors).
+  - Validates external links (with caching and retry logic).
+  - Reports flaws and can comment directly on GitHub Pull Requests.
+- **`check-github-github-links.ts`**: Ensures that we don't accidentally link to private `github/github` URLs in public documentation.
+- **`update-internal-links.ts`**: A CLI wrapper around the library function to perform bulk updates on the content files.
+
+## Setup & Usage
+
+### Validating Links
+
+To run the link checker locally:
+
+```bash
+npm run rendered-content-link-checker-cli
+```
+
+Options:
+- `--level <all|critical|warning>`: Set the reporting level.
+- `--check-external-links`: Check external links (slower).
+- `--verbose`: Show detailed output.
+
+### Updating Links
+
+If you have moved content or changed titles and need to update references:
+
+```bash
+npm run update-internal-links
+```
+
+This script typically relies on the state of the `content` directory to determine what needs updating.
+
+## Dependencies
+
+- **`cheerio`**: Used by the link checker to parse rendered HTML.
+- **`src/content-render`**: The link checker needs to render pages to see the final HTML output.
+- **`src/frame`**: Uses `cookies` and other utilities for request context.
+
+## Ownership
+
+- **Team**: `@github/docs-engineering`
+
+## Current State & Known Issues
+
+- **Performance**: The `rendered-content-link-checker` is resource-intensive because it renders pages. It uses concurrency limits and caching (especially for external links) to mitigate this.
+- **False Positives**: External link checking can be flaky due to temporary network issues or anti-bot protections on target sites. The system uses a "retry and cache" strategy to reduce noise.
+- **Liquid Complexity**: `update-internal-links` has to use regex and heuristics to parse Markdown mixed with Liquid, which is inherently fragile compared to a full AST parser, but necessary to preserve code formatting.

src/release-notes/README.md

@@ -1,3 +1,69 @@
-# Release notes
+# Release Notes
 
-Our release notes pages are specific to GitHub Enterprise Server (GHES). These pages list the change contained in each version of GHES.
+This module manages the fetching, processing, and rendering of GitHub Enterprise Server (GHES) release notes. These notes are displayed on dedicated pages (e.g., `/en/enterprise-server@3.19/admin/release-notes`) and list the features, bug fixes, and known issues for each patch release.
+
+## Purpose & Scope
+
+The primary goal is to:
+- **Parse Release Data**: Read structured YAML data containing release notes.
+- **Format & Sort**: Organize notes by version (major.minor) and patch level.
+- **Render Content**: Process Markdown and Liquid within the notes.
+- **Contextualize**: Inject the processed notes into the page context for rendering by React components.
+
+## Architecture
+
+### Data Source
+
+Release notes are stored in the `data/release-notes/enterprise-server` directory.
+- **Origin**: The content is sourced externally and synced to this repository.
+- **Format**: YAML files organized by version.
+- **Structure**: Each file contains entries for patch releases, including sections for "Features", "Bugs", "Security", etc.
+
+### Middleware
+
+The core logic resides in `src/release-notes/middleware/ghes-release-notes.ts`.
+- **Route Detection**: It activates only for GHES release notes pages or the Admin landing page.
+- **Data Retrieval**: Fetches raw data using `getReleaseNotes`.
+- **Forced English**: Currently, it forces the content language to English (`en`) during rendering. This is a workaround because the source Markdown often lacks Liquid variables for product names, leading to undesirable translations of proper nouns (e.g., "GitHub Copilot" becoming translated literally).
+- **Rendering**: Uses `renderPatchNotes` to process the Markdown/Liquid content of each note.
+
+### Library
+
+`src/release-notes/lib/release-notes-utils.ts` provides helper functions:
+- **`formatReleases`**: Sorts releases and patches semantically (using `semver`). It transforms the raw data into a structured array suitable for the UI.
+- **`renderPatchNotes`**: Iterates through sections (features, bugs, etc.) and renders the content strings.
+
+### Components
+
+The frontend rendering is handled by React components in `src/release-notes/components`:
+- **`GHESReleaseNotes.tsx`**: The main container.
+- **`PatchNotes.tsx`**: Renders the details of a specific patch.
+
+## Maintenance
+
+### Sourcing
+
+Release notes are received from an external source. **Do not manually create or edit release note files in this repository** unless specifically instructed to do so by the release process or for testing purposes.
+
+The files in `data/release-notes` are the destination for this external data.
+
+### URL Structure
+
+- **Page**: `/en/enterprise-server@<version>/admin/release-notes`
+- **Anchor**: `#3.19.1` (Links to specific patch notes)
+
+## Dependencies
+
+- **`semver`**: Used for sorting and comparing version strings.
+- **`src/versions`**: Used to determine supported GHES versions (`latestStable`, `all`).
+- **`src/content-render`**: Used to render the Markdown content within the notes.
+
+## Ownership
+
+- **Team**: `@github/docs-engineering`
+- **Content Owners**: The Writers and Release Managers responsible for the GHES release process.
+
+## Current State & Known Issues
+
+- **Translation Workaround**: As mentioned, we currently force English rendering for release notes to avoid "over-translation" of product names. This is a known limitation until the source data is updated to use proper Liquid variables.
+- **Legacy Redirects**: The middleware handles redirects for very old versions (pre-2.20) to `enterprise.github.com`.