diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics.md index 8b898418299c..ff551b46443c 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics.md +++ b/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. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md index a9b75065e6e2..dd3cb06612e4 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md +++ b/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: diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/enable-advanced-dashboards.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/enable-advanced-dashboards.md index 9a0babb997de..6b1f4d3fbbec 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/enable-advanced-dashboards.md +++ b/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. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md index 3f0b7d97fcaa..4ae7cfde50d2 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md +++ b/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 %} diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/setting-up-external-monitoring-with-opentelemetry.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/setting-up-external-monitoring-with-opentelemetry.md index f1818cef5138..07b2dbab397e 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/setting-up-external-monitoring-with-opentelemetry.md +++ b/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 diff --git a/src/links/README.md b/src/links/README.md index 1777c6799a5b..14e62b17a33b 100644 --- a/src/links/README.md +++ b/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 `` and `` 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 `: 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. \ No newline at end of file diff --git a/src/release-notes/README.md b/src/release-notes/README.md index f031fc705b49..d85a34287be2 100644 --- a/src/release-notes/README.md +++ b/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@/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`. \ No newline at end of file