feat: official vs community and instructions for downloads page (#7365)

* feat: official vs community and instructions for downloads page

* chore: semantical fixes

* chore: removed unused code

* chore: transform into a requirements table

* chore: update requirements

* chore: review changes

* Apply suggestions from code review

Co-authored-by: Michael Esteban <[email protected]>
Signed-off-by: Claudio W <[email protected]>

* Update apps/site/pages/en/about/previous-releases.mdx

Co-authored-by: Jordan Harband <[email protected]>
Signed-off-by: Claudio W <[email protected]>

* Update apps/site/pages/en/about/previous-releases.mdx

Co-authored-by: Jordan Harband <[email protected]>
Signed-off-by: Claudio W <[email protected]>

* Update previous-releases.mdx

Signed-off-by: Claudio W <[email protected]>

* Update COLLABORATOR_GUIDE.md

Co-authored-by: Caner Akdas <[email protected]>
Signed-off-by: Brian Muenzenmeyer <[email protected]>

* Update COLLABORATOR_GUIDE.md

Co-authored-by: Caner Akdas <[email protected]>
Signed-off-by: Brian Muenzenmeyer <[email protected]>

* Update COLLABORATOR_GUIDE.md

Co-authored-by: Caner Akdas <[email protected]>
Signed-off-by: Brian Muenzenmeyer <[email protected]>

* Update COLLABORATOR_GUIDE.md

Co-authored-by: Caner Akdas <[email protected]>
Signed-off-by: Brian Muenzenmeyer <[email protected]>

* Apply suggestions from code review

Co-authored-by: Caner Akdas <[email protected]>
Signed-off-by: Claudio W <[email protected]>

---------

Signed-off-by: Claudio W <[email protected]>
Signed-off-by: Brian Muenzenmeyer <[email protected]>
Co-authored-by: Michael Esteban <[email protected]>
Co-authored-by: Jordan Harband <[email protected]>
Co-authored-by: Brian Muenzenmeyer <[email protected]>
Co-authored-by: Caner Akdas <[email protected]>

Author: 5 people

COLLABORATOR_GUIDE.md

@@ -13,6 +13,9 @@
   - [Best practices when creating a Component](#best-practices-when-creating-a-component)
     - [How a new Component should look like when freshly created](#how-a-new-component-should-look-like-when-freshly-created)
   - [Best practices for Component development in general](#best-practices-for-component-development-in-general)
+- [The new Downloads page](#the-new-downloads-page)
+  - [Adding a Download Installation Method](#adding-a-download-installation-method)
+  - [Adding a Download Package Manager](#adding-a-download-package-manager)
 - [Unit Tests and Storybooks](#unit-tests-and-storybooks)
   - [General Guidelines for Unit Tests](#general-guidelines-for-unit-tests)
   - [General Guidelines for Storybooks](#general-guidelines-for-storybooks)
@@ -259,6 +262,117 @@ export default MyComponent;
   Use utilities or Hooks when you need a Reactive state
 - Avoid making your Component too big. Deconstruct it into smaller Components/Hooks whenever possible
 
+## The new Downloads page
+
+### Adding a Download Installation Method
+
+To add a new download installation method, follow these steps:
+
+1. **Update `INSTALL_METHODS` in `apps/site/util/downloadUtils.tsx`:**
+
+   - Add a new entry to the `INSTALL_METHODS` array.
+   - Each entry should have the following properties:
+     - `iconImage`: The React component of the icon image for the installation method. This should be an SVG component stored within `apps/site/components/Icons/InstallationMethod` and must follow the other icon component references (being a `FC` supporting `SVGSVGElement` props).
+       - Don't forget to add it on the `index.tsx` file from the `InstallationMethod` folder.
+     - `recommended`: A boolean indicating if this method is recommended. This property is available only for official installation methods.
+     - `url`: The URL for the installation method.
+     - `value`: The key of the installation method, which must be unique.
+
+   Example:
+
+   ```javascript
+   // filepath: /nodejs.org/apps/site/util/downloadUtils.tsx
+   // See full reference of INSTALL_METHODS within `downloadUtils.tsx`
+   export const INSTALL_METHODS = [
+     // ...existing methods...
+     {
+       iconImage: <InstallMethodIcons.YourIconImage width={16} height={16} />,
+       url: 'https://example.com/install',
+       value: 'exampleMethod',
+     },
+   ];
+   ```
+
+2. **Add translation key in `packages/i18n/locales/en.json`:**
+
+   - Add an entry under `layouts.download.codeBox.platformInfo` for the `info` property of the new installation method.
+
+   Example:
+
+   ```json
+   // filepath: /nodejs.org/packages/i18n/locales/en.json
+   {
+     "layouts": {
+       "download": {
+         "codeBox": {
+           "platformInfo": {
+             "exampleMethod": "Example installation method description."
+           }
+         }
+       }
+     }
+   }
+   ```
+
+3. **Update `InstallationMethodLabel` and `InstallationMethod` in `@/types/release.ts`:**
+
+   - Add the new method to the `InstallationMethodLabel` and `InstallationMethod` types.
+
+   Example:
+
+   ```typescript
+   // filepath: /nodejs.org/apps/site/types/release.ts
+   export type InstallationMethod = 'exampleMethod' | 'anotherMethod' | ...;
+
+   export const InstallationMethodLabel: Record<InstallationMethod, string> = {
+     exampleMethod: 'Example Method',
+     anotherMethod: 'Another Method',
+     // ...existing methods...
+   };
+   ```
+
+4. **Add a snippet in `apps/site/snippets/en/download`:**
+
+   - Create a new file with the same key as the `value` property (e.g., `exampleMethod.bash`).
+   - Add the installation instructions in this file.
+   - The snippet file can use JavaScript template syntax and has access to a `props` variable of type `ReleaseContextType`.
+
+   Example:
+
+   ```bash
+   // filepath: /nodejs.org/apps/site/snippets/en/download/exampleMethod.bash
+   echo "Installing Node.js version ${props.version} using Example Method"
+   ```
+
+5. **Configure `compatibility` within the `INSTALL_METHODS` object in `downloadUtils.ts`:**
+
+- Use the `compatibility` property to enable/list the installation method for specific OSs, Node.js version ranges, or architectures/platforms.
+
+Example:
+
+```javascript
+// filepath: /nodejs.org/apps/site/util/downloadUtils.tsx
+// See full reference of compatibility property within `downloadUtils.tsx`
+export const INSTALL_METHODS = [
+  {
+    iconImage: 'path/to/icon.svg',
+    url: 'https://example.com/install',
+    value: 'exampleMethod',
+    compatibility: {
+      os: ['LINUX', 'MAC'],
+      semver: ['>=14.0.0'],
+      platform: ['x64', 'arm64'],
+    },
+  },
+];
+```
+
+By following these steps, you can successfully add a new download installation method to the Node.js website.
+
+### Adding a Download Package Manager
+
+You can add a PACKAGE_MANAGER the same way as adding an INSTALLATION_METHOD (from the section above, "Adding a Download Installation Method") but it should be added to the PACKAGE_MANAGERS object in `apps/site/util/downloadUtils.tsx`.
+
 ## Unit Tests and Storybooks
 
 Each new feature or bug fix should be accompanied by a unit test (when deemed valuable).

apps/site/components/Downloads/DownloadReleasesTable.tsx

@@ -1,9 +1,10 @@
 import { getTranslations } from 'next-intl/server';
 import type { FC } from 'react';
 
+import LinkWithArrow from '@/components/LinkWithArrow';
 import getReleaseData from '@/next-data/releaseData';
+import { BASE_CHANGELOG_URL } from '@/next.constants.mjs';
 import { getNodeApiLink } from '@/util/getNodeApiLink';
-import { getNodeJsChangelog } from '@/util/getNodeJsChangelog';
 
 // This is a React Async Server Component
 // Note that Hooks cannot be used in a RSC async component
@@ -17,11 +18,12 @@ const DownloadReleasesTable: FC = async () => {
     <table id="tbVersions" className="download-table full-width">
       <thead>
         <tr>
-          <th>Node.js Version</th>
-          <th>Module Version</th>
-          <th>Codename</th>
-          <th>Release Date</th>
-          <th colSpan={2}>npm</th>
+          <th>{t('components.downloadReleasesTable.version')}</th>
+          <th>{t('components.downloadReleasesTable.nApiVersion')}</th>
+          <th>{t('components.downloadReleasesTable.codename')}</th>
+          <th>{t('components.downloadReleasesTable.releaseDate')}</th>
+          <th>{t('components.downloadReleasesTable.npmVersion')}</th>
+          <th></th>
         </tr>
       </thead>
       <tbody>
@@ -35,17 +37,19 @@ const DownloadReleasesTable: FC = async () => {
             </td>
             <td data-label="npm">v{release.npm}</td>
             <td className="download-table-last">
-              <a
+              <LinkWithArrow
                 href={`https://nodejs.org/download/release/${release.versionWithPrefix}/`}
               >
-                {t('components.downloadReleasesTable.releases')}
-              </a>
-              <a href={getNodeJsChangelog(release.versionWithPrefix)}>
-                {t('components.downloadReleasesTable.changelog')}
-              </a>
-              <a href={getNodeApiLink(release.versionWithPrefix)}>
-                {t('components.downloadReleasesTable.docs')}
-              </a>
+                {t('components.downloadReleasesTable.actions.releases')}
+              </LinkWithArrow>
+
+              <LinkWithArrow href={`${BASE_CHANGELOG_URL}${release.version}`}>
+                {t('components.downloadReleasesTable.actions.changelog')}
+              </LinkWithArrow>
+
+              <LinkWithArrow href={getNodeApiLink(release.versionWithPrefix)}>
+                {t('components.downloadReleasesTable.actions.docs')}
+              </LinkWithArrow>
             </td>
           </tr>
         ))}

apps/site/components/Downloads/Release/ChangelogLink.tsx

@@ -3,8 +3,8 @@
 import type { FC, PropsWithChildren } from 'react';
 import { useContext } from 'react';
 
-import LinkWithArrow from '@/components/Downloads/Release/LinkWithArrow';
 import Link from '@/components/Link';
+import LinkWithArrow from '@/components/LinkWithArrow';
 import { BASE_CHANGELOG_URL } from '@/next.constants.mjs';
 import { ReleaseContext } from '@/providers/releaseProvider';
 

apps/site/components/Downloads/Release/ReleaseCodeBox.tsx

@@ -8,14 +8,13 @@ import AlertBox from '@/components/Common/AlertBox';
 import CodeBox from '@/components/Common/CodeBox';
 import Skeleton from '@/components/Common/Skeleton';
 import Link from '@/components/Link';
+import LinkWithArrow from '@/components/LinkWithArrow';
 import { createSval } from '@/next.jsx.compiler.mjs';
 import { ReleaseContext, ReleasesContext } from '@/providers/releaseProvider';
 import type { ReleaseContextType } from '@/types/release';
 import { INSTALL_METHODS } from '@/util/downloadUtils';
 import { highlightToHtml } from '@/util/getHighlighter';
 
-import LinkWithArrow from './LinkWithArrow';
-
 // Creates a minimal JavaScript interpreter for parsing the JavaScript code from the snippets
 // Note: that the code runs inside a sandboxed environment and cannot interact with any code outside of the sandbox
 // It also does not have access to any Global or Window objects, nor it can execute code on the end-user's browser

apps/site/components/Icons/Platform/Choco.tsx renamed to apps/site/components/Icons/InstallationMethod/Choco.tsx

@@ -0,0 +1,7 @@
+import Choco from '@/components/Icons/InstallationMethod/Choco';
+import Docker from '@/components/Icons/InstallationMethod/Docker';
+import FNM from '@/components/Icons/InstallationMethod/FNM';
+import Homebrew from '@/components/Icons/InstallationMethod/Homebrew';
+import NVM from '@/components/Icons/InstallationMethod/NVM';
+
+export default { Choco, Docker, FNM, Homebrew, NVM };