@redpanda-data/docs-extensions-and-macros 4.0.0 → 4.2.0

package/README.adoc

@@ -254,6 +254,90 @@ antora:
     - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories'
 ```
 
+=== Compute end-of-life extension
+
+This extension calculates and attaches metadata related to the end-of-life (EoL) status of docs pages, such as nearing EoL, past EoL, and associated EoL dates. This metadata can be used to display relevant banners or messages in docs to inform users about the lifecycle of each version.
+
+The extension leverages configuration settings provided in the Antora playbook to apply EoL calculations, specify the warning period, and include links to upgrade documentation and EoL policies.
+
+The extension computes whether a page is nearing EoL or past EoL based on the `page-release-date` attribute and configured settings.
+It injects the following attributes into each page, making them available for use in UI templates:
+
+- `page-is-nearing-eol`: Indicates if the page is within the warning period before EoL. Calculated using `(page-release-date + supported_months) - warning_weeks`.
+- `page-is-past-eol`: Indicates if the page has passed its EoL. Calculated using `today > (page-release-date + supported_months)`.
+- `page-eol-date`: The calculated EoL date in a human-readable format. Calculated using `page-release-date + supported_months`.
+- `page-eol-doc`: The URL to the supported versions policy or EoL documentation.
+- `page-upgrade-doc`: The Antora resource ID to a document containing upgrade instructions.
+
+==== Environment variables
+
+This extension does not require any environment variables.
+
+==== Configuration options
+
+To enable and configure the extension, add it to the `antora.extensions` section of your Antora playbook. Define the EoL settings under the `data.eol_settings` key with the following options:
+
+`component` (required):: The component name to which the configuration applies.
+`eol_doc` (required):: A link to the supported versions policy or EoL documentation.
+`upgrade_doc` (required):: A link to the upgrade instructions.
+`supported_months` (optional, default: 12):: The number of months after the publish date when the documentation reaches its EoL.
+`warning_weeks` (optional, default: 6):: The number of weeks before EoL when the documentation is considered to be nearing EoL. Can be used to decide when to notify users of the upcoming EoL status.
+
+[,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/compute-end-of-life'
+      data:
+        eol_settings:
+          - component: 'ROOT'
+            supported_months: 18
+            warning_weeks: 8
+            eol_doc: https://support.redpanda.com/hc/en-us/articles/20617574366743-Redpanda-Supported-Versions
+            upgrade_doc: ROOT:upgrade:index.adoc
+----
+
+==== Registration example
+
+You can register the extension with a customized configuration for different components in your playbook:
+
+[,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/compute-end-of-life'
+      data:
+        eol_settings:
+          - component: 'ROOT'
+            supported_months: 12
+            warning_weeks: 6
+            eol_doc: https://example.com/supported-versions
+            upgrade_doc: ROOT:upgrade:index.adoc
+          - component: 'example-docs'
+            supported_months: 24
+            warning_weeks: 12
+            eol_doc: https://example.com/example-supported-versions
+            upgrade_doc: example-docs:upgrade:index.adoc
+----
+
+
+==== Example Handlebars template:
+
+[,handlebars]
+----
+{{#if page.attributes.is-nearing-eol}}
+  <div class="banner-container nearing-eol">
+    This documentation will reach its end of life on {{page.attributes.eol-date}}.
+    Please <a href="{{resolve-resource page.attributes.upgrade-doc}}">upgrade to a supported version</a>.
+  </div>
+{{else if page.attributes.is-past-eol}}
+  <div class="banner-container past-eol">
+    This documentation reached its end of life on {{page.attributes.eol-date}}.
+    See our <a href="{{page.attributes.eol-doc}}" target="_blank">supported versions policy</a>.
+  </div>
+{{/if}}
+----
+
 === Generate index data
 
 The `generate-index-data` extension creates structured index data about doc pages based on configurable filters. The indexed data is saved to a specified attribute in all component versions, enabling the dynamic generation of categorized links and descriptions within your docs using UI templates.

package/extensions/compute-end-of-life.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const calculateEOL = require('./util/calculate-eol.js');
+
+module.exports.register = function ({ config }) {
+  this.on('contentClassified', ({ contentCatalog }) => {
+    const logger = this.getLogger("compute-end-of-life-extension");
+
+    // Extract EOL configuration from the config object
+    const eolConfigs = config.data?.eol_settings || [];
+    if (!Array.isArray(eolConfigs) || eolConfigs.length === 0) {
+      logger.warn('No end-of-life settings found in configuration.');
+      return;
+    }
+
+    eolConfigs.forEach(({ component: componentName, supported_months, warning_weeks, eol_doc, upgrade_doc }) => {
+      if (!eol_doc || !upgrade_doc) {
+        logger.error(
+          `End-of-life configuration for component "${component}" is missing required attributes. ` +
+          `Ensure both "eol_doc" and "upgrade_doc" are specified.`
+        );
+        return;
+      }
+      const resolvedEOLMonths = supported_months && supported_months > 0 ? supported_months : 12; // Default: 12 months
+      const resolvedWarningWeeks = warning_weeks && warning_weeks > 0 ? warning_weeks : 6; // Default: 6 weeks
+
+      logger.info(
+        `Processing component: ${componentName} with end-of-life months: ${resolvedEOLMonths}, Warning weeks: ${resolvedWarningWeeks}`
+      );
+
+      const component = contentCatalog.getComponents().find((c) => c.name === componentName);
+
+      if (!component) {
+        logger.warn(`Component not found: ${componentName}`);
+        return;
+      }
+
+      component.versions.forEach(({ asciidoc, version }) => {
+        const releaseDate = asciidoc.attributes['page-release-date'];
+        if (releaseDate) {
+          // Pass resolved configuration to calculateEOL
+          const eolInfo = calculateEOL(releaseDate, resolvedEOLMonths, resolvedWarningWeeks, logger);
+          Object.assign(asciidoc.attributes, {
+            'page-is-nearing-eol': eolInfo.isNearingEOL.toString(),
+            'page-is-past-eol': eolInfo.isPastEOL.toString(),
+            'page-eol-date': eolInfo.eolDate,
+            'page-eol-doc': eol_doc,
+            'page-upgrade-doc': upgrade_doc,
+          });
+        } else {
+          logger.warn(`No release date found for component: ${componentName}. Make sure to set {page-release-date} in the antora.yml of the component version ${version}.`);
+        }
+      });
+    });
+  });
+};

package/extensions/util/calculate-eol.js

@@ -0,0 +1,55 @@
+'use strict';
+
+module.exports = (releaseDate, eolMonths, warningWeeks, logger) => {
+  if (!releaseDate) {
+    logger.warn(
+      'No release date provided. Make sure to set {page-release-date} in the antora.yml of the component.'
+    );
+    return null;
+  }
+
+  // Parse the input date string YYYY-MM-DD in UTC
+  const parseUTCDate = (dateString) => {
+    const [year, month, day] = dateString.split('-').map(Number);
+    // month - 1 because JS months are 0-based
+    // https://www.w3schools.com/jsref/jsref_getmonth.asp
+    return new Date(Date.UTC(year, month - 1, day));
+  };
+
+  const targetDate = parseUTCDate(releaseDate);
+
+  if (isNaN(targetDate.getTime())) {
+    logger.warn('Invalid release date format:', releaseDate);
+    return null;
+  }
+
+  // Calculate EoL date in UTC
+  const eolDate = new Date(targetDate.getTime()); // clone
+  eolDate.setUTCMonth(eolDate.getUTCMonth() + eolMonths);
+
+  // Calculate the threshold for warning (X weeks before EoL) in UTC
+  const weeksBeforeEOL = new Date(eolDate.getTime());
+  weeksBeforeEOL.setUTCDate(weeksBeforeEOL.getUTCDate() - warningWeeks * 7);
+
+  // Compare times in milliseconds to avoid timezone confusion
+  const nowMs = Date.now();
+  const eolMs = eolDate.getTime();
+  const warningMs = weeksBeforeEOL.getTime();
+
+  const isNearingEOL = nowMs >= warningMs && nowMs < eolMs;
+  const isPastEOL = nowMs > eolMs;
+
+  // Format the EoL date in UTC
+  const humanReadableEOLDate = new Intl.DateTimeFormat('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC', // Ensure UTC in output
+  }).format(eolDate);
+
+  return {
+    isNearingEOL,
+    isPastEOL,
+    eolDate: humanReadableEOLDate, // For example "March 1, 2025"
+  };
+};

package/extensions/util/custom-stringify.js

@@ -0,0 +1,19 @@
+function customStringify(obj) {
+  return JSON.stringify(obj, (key, value) => {
+    if (value instanceof Map) {
+      return {
+        type: 'Map',
+        value: Array.from(value.entries())
+      };
+    } else if (value instanceof Set) {
+      return {
+        type: 'Set',
+        value: Array.from(value)
+      };
+    } else if (typeof value === 'function') {
+      return value.toString();
+    } else {
+      return value;
+    }
+  }, 2);
+}

package/extensions/version-fetcher/fetch-latest-docker-tag.js

@@ -0,0 +1,66 @@
+/**
+ * Fetches the latest version tag from Docker Hub for a given repository.
+ *
+ *
+ * @param {string} dockerNamespace - The Docker Hub namespace (organization or username)
+ * @param {string} dockerRepo - The repository name on Docker Hub
+ * @returns {Promise<string|null>} The latest version tag or null if none is found.
+ */
+module.exports = async (dockerNamespace, dockerRepo) => {
+  const { default: fetch } = await import('node-fetch');
+
+  try {
+    // Fetch a list of tags from Docker Hub.
+    const url = `https://hub.docker.com/v2/repositories/${dockerNamespace}/${dockerRepo}/tags?page_size=100`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new Error(`Docker Hub API responded with status ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    // Define a regular expression to capture the major and minor version numbers.
+    // The regex /^v(\d+)\.(\d+)/ matches tags that start with "v", followed by digits (major),
+    // a period, and more digits (minor). It works for tags like "v2.3.8-24.3.6" or "v25.1-k8s4".
+    const versionRegex = /^v(\d+)\.(\d+)/;
+
+    // Filter the list of tags to include only those that match our expected version pattern.
+    // This helps ensure we work only with tags that represent valid version numbers.
+    let versionTags = data.results.filter(tag => versionRegex.test(tag.name));
+
+    // If the repository is "redpanda-operator", ignore any tags starting with the old "v22 or "v23" versions.
+    if (dockerRepo === 'redpanda-operator') {
+      versionTags = versionTags.filter(tag => !/^(v22|v23)/.test(tag.name));
+    }
+
+    if (versionTags.length === 0) {
+      console.warn('No version tags found.');
+      return null;
+    }
+
+    // Sort the filtered tags in descending order based on their major and minor version numbers.
+    // This sorting ignores any additional patch or suffix details and focuses only on the major.minor value.
+    versionTags.sort((a, b) => {
+      const aMatch = a.name.match(versionRegex);
+      const bMatch = b.name.match(versionRegex);
+      const aMajor = parseInt(aMatch[1], 10);
+      const aMinor = parseInt(aMatch[2], 10);
+      const bMajor = parseInt(bMatch[1], 10);
+      const bMinor = parseInt(bMatch[2], 10);
+
+      // Compare by major version first; if equal, compare by minor version.
+      if (aMajor !== bMajor) {
+        return bMajor - aMajor;
+      }
+      return bMinor - aMinor;
+    });
+
+    // Return the name of the tag with the highest major.minor version.
+    return versionTags[0].name;
+
+  } catch (error) {
+    console.error('Error fetching latest Docker tag:', error);
+    return null;
+  }
+};

package/extensions/version-fetcher/set-latest-version.js

@@ -3,7 +3,7 @@
 module.exports.register = function ({ config }) {
   const GetLatestRedpandaVersion = require('./get-latest-redpanda-version');
   const GetLatestConsoleVersion = require('./get-latest-console-version');
-  const GetLatestOperatorVersion = require('./get-latest-operator-version');
+  const GetLatestOperatorVersion = require('./fetch-latest-docker-tag');
   const GetLatestHelmChartVersion = require('./get-latest-redpanda-helm-version');
   const GetLatestConnectVersion = require('./get-latest-connect');
   const logger = this.getLogger('set-latest-version-extension');
@@ -25,6 +25,7 @@ module.exports.register = function ({ config }) {
       auth: process.env.REDPANDA_GITHUB_TOKEN || undefined,
     };
     const github = new OctokitWithRetries(githubOptions);
+    const dockerNamespace = 'redpandadata'
 
     try {
       const [
@@ -36,7 +37,7 @@ module.exports.register = function ({ config }) {
       ] = await Promise.allSettled([
         GetLatestRedpandaVersion(github, owner, 'redpanda'),
         GetLatestConsoleVersion(github, owner, 'console'),
-        GetLatestOperatorVersion(github, owner, 'redpanda-operator'),
+        GetLatestOperatorVersion(dockerNamespace, 'redpanda-operator'),
         GetLatestHelmChartVersion(github, owner, 'helm-charts', 'charts/redpanda/Chart.yaml'),
         GetLatestConnectVersion(github, owner, 'connect'),
       ]);
@@ -49,6 +50,8 @@ module.exports.register = function ({ config }) {
         connect: latestConnectResult.status === 'fulfilled' ? latestConnectResult.value : undefined,
       };
 
+      console.log(latestVersions)
+
       const components = await contentCatalog.getComponents();
       components.forEach(component => {
         const prerelease = component.latestPrerelease;
@@ -58,24 +61,25 @@ module.exports.register = function ({ config }) {
             asciidoc.attributes['page-component-version-is-prerelease'] = 'true';
           }
 
-          // Set operator and helm chart attributes
-          if (latestVersions.operator) {
-            asciidoc.attributes['latest-operator-version'] = latestVersions.operator;
-          }
-          if (latestVersions.helmChart) {
-            asciidoc.attributes['latest-redpanda-helm-chart-version'] = latestVersions.helmChart;
-          }
+          // Set operator and helm chart attributes via helper function
+          updateAttributes(asciidoc, [
+            { condition: latestVersions.operator, key: 'latest-operator-version', value: latestVersions.operator },
+            { condition: latestVersions.helmChart, key: 'latest-redpanda-helm-chart-version', value: latestVersions.helmChart }
+          ]);
 
           // Set attributes for console and connect versions
-          if (latestVersions.console) {
-            setVersionAndTagAttributes(asciidoc, 'latest-console', latestVersions.console.latestStableRelease, name, version);
-          }
-          if (latestVersions.connect) {
-            setVersionAndTagAttributes(asciidoc, 'latest-connect', latestVersions.connect, name, version);
-          }
+          [
+            { condition: latestVersions.console, baseName: 'latest-console', value: latestVersions.console?.latestStableRelease },
+            { condition: latestVersions.connect, baseName: 'latest-connect', value: latestVersions.connect }
+          ].forEach(mapping => {
+            if (mapping.condition && mapping.value) {
+              setVersionAndTagAttributes(asciidoc, mapping.baseName, mapping.value, name, version);
+            }
+          });
+
           // Special handling for Redpanda RC versions if in beta
           if (latestVersions.redpanda?.latestRcRelease?.version) {
-            setVersionAndTagAttributes(asciidoc, 'redpanda-beta', latestVersions.redpanda.latestRcRelease.version, name, version)
+            setVersionAndTagAttributes(asciidoc, 'redpanda-beta', latestVersions.redpanda.latestRcRelease.version, name, version);
             setVersionAndTagAttributes(asciidoc, 'console-beta', latestVersions.console.latestBetaRelease, name, version);
             asciidoc.attributes['redpanda-beta-commit'] = latestVersions.redpanda.latestRcRelease.commitHash;
           }
@@ -127,4 +131,13 @@ module.exports.register = function ({ config }) {
   function sanitizeVersion(version) {
     return version.replace(/^v/, '');
   }
-};
+
+  // Helper function to update multiple attributes based on a list of mappings
+  function updateAttributes(asciidoc, mappings) {
+    mappings.forEach(({ condition, key, value }) => {
+      if (condition) {
+        asciidoc.attributes[key] = value;
+      }
+    });
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -33,6 +33,7 @@
     "./extensions/archive-attachments": "./extensions/archive-attachments.js",
     "./extensions/add-pages-to-root": "./extensions/add-pages-to-root.js",
     "./extensions/collect-bloblang-samples": "./extensions/collect-bloblang-samples.js",
+    "./extensions/compute-end-of-life": "./extensions/compute-end-of-life.js",
     "./extensions/generate-rp-connect-categories": "./extensions/generate-rp-connect-categories.js",
     "./extensions/generate-index-data": "./extensions/generate-index-data.js",
     "./extensions/generate-rp-connect-info": "./extensions/generate-rp-connect-info.js",
@@ -74,6 +75,7 @@
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
     "micromatch": "^4.0.8",
+    "node-fetch": "^3.3.2",
     "node-html-parser": "5.4.2-0",
     "papaparse": "^5.4.1",
     "semver": "^7.6.0",

package/extensions/util/customStringify.js

@@ -1,19 +0,0 @@
-function customStringify(obj) {
-    return JSON.stringify(obj, (key, value) => {
-        if (value instanceof Map) {
-            return {
-                type: 'Map',
-                value: Array.from(value.entries())
-            };
-        } else if (value instanceof Set) {
-            return {
-                type: 'Set',
-                value: Array.from(value)
-            };
-        } else if (typeof value === 'function') {
-            return value.toString();
-        } else {
-            return value;
-        }
-    }, 2);
-}

package/extensions/version-fetcher/get-latest-operator-version.js

@@ -1,10 +0,0 @@
-module.exports = async (github, owner, repo) => {
-  try {
-    const release = await github.rest.repos.getLatestRelease({ owner, repo });
-    latestOperatorReleaseVersion = release.data.tag_name;
-    return latestOperatorReleaseVersion;
-  } catch (error) {
-    console.error(error);
-    return null;
-  }
-};