diff --git a/.lintstagedrc b/.lintstagedrc index 62083dfa6dfd5..c8516eb2555b4 100644 --- a/.lintstagedrc +++ b/.lintstagedrc @@ -1,3 +1,4 @@ { - "**/*": ["eslint --fix", "prettier --write"] + "**/*.{js,mjs,ts,tsx,md,mdx}": ["eslint --fix"], + "**/*.{js,mjs,ts,tsx,md,mdx,json,yml}": ["prettier --write"] } diff --git a/.remarkrc b/.remarkrc index c7ef88977fc9e..e908e885412b6 100644 --- a/.remarkrc +++ b/.remarkrc @@ -2,37 +2,13 @@ "plugins": [ "remark-preset-lint-node", "preset-prettier", - [ - "remark-lint-fenced-code-flag", - false - ], - [ - "remark-lint-first-heading-level", - false - ], - [ - "remark-lint-maximum-line-length", - false - ], - [ - "remark-lint-no-file-name-articles", - false - ], - [ - "remark-lint-no-literal-urls", - false - ], - [ - "remark-lint-no-undefined-references", - false - ], - [ - "remark-lint-prohibited-strings", - false - ], - [ - "remark-preset-lint-node/remark-lint-nodejs-links.js", - false - ] + ["remark-lint-fenced-code-flag", false], + ["remark-lint-first-heading-level", false], + ["remark-lint-maximum-line-length", false], + ["remark-lint-no-file-name-articles", false], + ["remark-lint-no-literal-urls", false], + ["remark-lint-no-undefined-references", false], + ["remark-lint-prohibited-strings", false], + ["remark-preset-lint-node/remark-lint-nodejs-links.js", false] ] } diff --git a/.storybook/test-runner.ts b/.storybook/test-runner.ts index dfae8a9e2700b..81da6dcd41940 100644 --- a/.storybook/test-runner.ts +++ b/.storybook/test-runner.ts @@ -1,12 +1,14 @@ import type { TestRunnerConfig } from '@storybook/test-runner'; const config: TestRunnerConfig = { - async postRender(page, _context) { + postRender: async (page, context) => { + // Gather the page HTML inner content for a DOM HTML Snapshot const rootElementId = '[data-test-id="story-root"]'; const rootElement = await page.locator(rootElementId); const content = await rootElement.innerHTML(); + expect(content).toBeDefined(); - expect(content).toMatchSnapshot(); + expect(content.replace(/class="(.*?)"/gm, '')).toMatchSnapshot(); }, }; diff --git a/CONTENT_VS_CODE.md b/CONTENT_VS_CODE.md index c27744aaee35d..43342c46db78b 100644 --- a/CONTENT_VS_CODE.md +++ b/CONTENT_VS_CODE.md @@ -2,4 +2,6 @@ The **Website Team** (@nodejs/website) is primarily concerned with the code and overall structure of the website. -The content of the website comes from a variety of working groups [(Release WG, Ecosystem Security WG and others)](https://github.com/nodejs/TSC/blob/main/WORKING_GROUPS.md#current-working-groups). The Website team defers to these WGs on matters of content and routinely adds collaborators from these working groups as they add and improve content on the website. In other words, the Website team is not an _editorial_ team except when no other Working Group has taken responsibility for a content area, meaning we are the default editors for that content. +The content of the website comes from a variety of working groups [(Release WG, Ecosystem Security WG and others)](https://github.com/nodejs/TSC/blob/main/WORKING_GROUPS.md#current-working-groups). + +The Website team defers to these WGs on matters of content and routinely adds collaborators from these working groups as they add and improve content on the website. In other words, the Website team is not an **editorial** team except when no other Working Group has taken responsibility for a content area, meaning we are the default editors for that content. diff --git a/DEPENDENCY_PINNING.md b/DEPENDENCY_PINNING.md new file mode 100644 index 0000000000000..617b09148b243 --- /dev/null +++ b/DEPENDENCY_PINNING.md @@ -0,0 +1,35 @@ +## Dependency Pinning + +Based on the initial discussions from [this discussion thread](https://github.com/nodejs/nodejs.org/discussions/5491), we've decided to use a more strict strategy for handling NPM dependencies within the Node.js Website. + +The intent here is to prevent the build process, or the website itself, from breaking due to changes in dependencies. As some dependencies do not respect semantic versioning, this is a real concern. Pinning dependencies also ensures that we stay fixed on a specific dependency version. For security updates, Dependabot is still configured to give us security alerts when specific dependencies got security advisories. + +### When adding dependencies + +The following recommendations are in order when adding a new dependency: + +- A dependency should be a `dependencies` if it is part of the build process of the Website or used within runtime code. + - Some non-code dependencies are required for the bootstrap of the repository. They are either used on basic build scripts or Git Hooks. Examples include `husky`, `lint-staged` and others. +- A dependency should be a `devDependencies` if it is not invoked anywhere within the codebase. + - This applies to runtimes, tooling, utility/dev-only commands, type packages and others +- Sometimes, a dependency should be a `devDependency` even if invoked within the codebase, but only used within a development environment or during a test runner. Examples include `jest`, `storybook` and others. +- A dependency should be a `peerDependencies` if it is a runtime dependency of the Website, but the Website itself does not install it. Examples include `react`, `react-dom` and others. + +### When pinning dependencies + +When adding dependencies, you should consider if that dependency should be saved as an exact dependency (`--save-exact`) or use either a `^` or `~` version range operator. The following guidelines are in order: + +- A dependency, in general, should be pinned to its exact dependency if it's either a tooling or a CLI dependency. Examples include `husky`, `prettier`, `jest` and others. +- A dependency should generally use `~` if we're interested in patch updates (such as hot-fixes and bug-fixes) and the package is part of the Development or Testing Environment. (Such as `storybook`, for example) +- A dependency should generally use `^` if they're part of the Website Application itself, such as `react`, `react-intl` etc. This is done because we intentionally want to get these dependencies' latest features and bug-fixes. + - If we're not interested in getting the latest features and bug fixes, we should consider using `~` instead. +- Node. js-only dependencies used in scripts or during the build process of the Website (not used within actual Application code) should use `~` instead. Examples include `glob`, `@nodevu/core` +- TypeScript type packages of corresponding packages should follow the same `semver` of their respective packages + +### About manual updates + +This document intends to outline the strategy we have when adding dependencies. We also recommend that Team members only add new dependencies when explicitly needed. The more dependencies, the harder it gets to review and understand the complexity of the Website Application. You can avoid adding new dependencies if possible. + +Manual updates should be avoided. Dependabot is configured for updating our dependencies. Updating a dependency is only needed if the update breaks the current `semver` constraint. In these situations, good judgement should be used (as a dependency should generally only be updated in these scenarios if the updated version brings new features desired by the team). + +Lastly, in general, a Pull Request should not contain `package-lock.json` changes, nor changes to dependencies on `package.json`. diff --git a/README.md b/README.md index e740f5ac871ba..0801ab452f375 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ ## What is this repo? -[Nodejs.org](https://nodejs.org/) by the [OpenJS Foundation](https://openjsf.org/) is the official website for the Node.js® JavaScript runtime. This repo is the source code for the website. It is build using [Next.js](https://nextjs.org) a React Framework. +[Nodejs.org](https://nodejs.org/) by the [OpenJS Foundation](https://openjsf.org/) is the official website for the Node.js® JavaScript runtime. This repo is the source code for the website. It is built using [Next.js](https://nextjs.org), a React Framework. ### Quick-Start Locally @@ -50,20 +50,20 @@ npx turbo serve - Initial development usually happens in English: `/pages/en` - `/i18n/locales/{{locale}}.json` is where global localization information lives. - All content is in Markdown and is per locale. - - The top of each Markdown file is a block of YAML (Frontmatter) for page specific localization information that is passed to various templates. + - The top of each Markdown file is a block of YAML (Frontmatter) for page-specific localization information passed to various templates. - The bulk of the Markdown content for each page is referenced as `{children}` on their respective JSX Layout (`layouts/`) ## Contributing This project adopts the Node.js [Code of Conduct][]. -Any person who wants to contribute to the Website is welcome! Please read [Contributing Guidelines][] and see the [Figma Design][] to understand better the structure of this repository. +Any person who wants to contribute to the Website is welcome! Please read [Contribution Guidelines][] and see the [Figma Design][] to understand better the structure of this repository. ### To translate content into other languages -If you want to help translate to other languages or improve existing translations, it isn't necessary to work from GitHub. You can and should do it through Crowdin, this is the correct workflow. +If you want to help translate to other languages or improve existing translations, it is optional to work from GitHub. You can and should do it through Crowdin; this is the correct workflow. -Crowdin is an online tool that facilitates the user experience for the translator, here is more information: +Crowdin is an online tool that facilitates the user experience for the translator; here is more information: Website translations are handled via [Crowdin](https://crowdin.com/project/nodejs-website). @@ -71,13 +71,13 @@ To help with localization, please read the [Translation](TRANSLATION.md) guide. ### Deployment -Full setup is in minus secrets and certificates. The webhook is setup on GitHub for this project and talks to a small Node server on the host which does the work. See the [github-webhook](https://github.com/rvagg/github-webhook) package for this. +Full setup is in minus secrets and certificates. The webhook is set up on GitHub for this project and talks to a small Node server on the host, which does the work. See the [github-webhook](https://github.com/rvagg/github-webhook) package for this. ## Relevant Links [Code of Conduct][] -[Contributing Guidelines][] +[Contribution Guidelines][] [Collaborator Guide][] @@ -85,8 +85,11 @@ Full setup is in +
History diff --git a/components/Api/Stability/__snapshots__/index.stories.tsx.snap b/components/Api/Stability/__snapshots__/index.stories.tsx.snap index bf0cddde37331..834e39b59d858 100644 --- a/components/Api/Stability/__snapshots__/index.stories.tsx.snap +++ b/components/Api/Stability/__snapshots__/index.stories.tsx.snap @@ -1,7 +1,7 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP exports[`Api/Stability Default smoke-test 1`] = ` -
+
Stability: 0 - This is an stability index example
`; diff --git a/components/Article/AuthorList/Author/__snapshots__/index.stories.tsx.snap b/components/Article/AuthorList/Author/__snapshots__/index.stories.tsx.snap index 1d1999f03e01f..4320ab68a0c40 100644 --- a/components/Article/AuthorList/Author/__snapshots__/index.stories.tsx.snap +++ b/components/Article/AuthorList/Author/__snapshots__/index.stories.tsx.snap @@ -1,8 +1,7 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP exports[`Article/AuthorList/Author Default smoke-test 1`] = ` - +
Article Authors
  • -
  • -
  • -
  • - +
    This is a block quote
    `; exports[`Article/BlockQuote MultipleParagraph smoke-test 1`] = ` -
    +

    This is a block quote 1

    diff --git a/components/Article/Codebox/__snapshots__/index.stories.tsx.snap b/components/Article/Codebox/__snapshots__/index.stories.tsx.snap index decf2593ea9e9..91223627a3c87 100644 --- a/components/Article/Codebox/__snapshots__/index.stories.tsx.snap +++ b/components/Article/Codebox/__snapshots__/index.stories.tsx.snap @@ -1,33 +1,29 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP exports[`Article/Codebox Default smoke-test 1`] = ` -
    -  
    
-    
    
-      
     
    
-    
   
    
-  
    
-    
+  
    
+    
       const
     
     a
-    
+    
       =
     
-    
+    
       1
     
-    
+    
       ;
     
   
    
@@ -35,47 +31,41 @@ exports[`Article/Codebox Default smoke-test 1`] = `
 `;
 
 exports[`Article/Codebox MultiLang smoke-test 1`] = `
-
    -  
    
-    
    
-      
-      
     
    
-    
   
    
-  
    
-    
+  
    
+    
       const
     
     http
-    
+    
       =
     
-    
+    
       require
     
-    
+    
       (
     
-    
+    
       'http'
     
-    
+    
       )
     
-    
+    
       ;
     
   
    
diff --git a/components/Article/EditLink/__snapshots__/index.stories.tsx.snap b/components/Article/EditLink/__snapshots__/index.stories.tsx.snap
index 39225d6f0be02..67b912d211c9f 100644
--- a/components/Article/EditLink/__snapshots__/index.stories.tsx.snap
+++ b/components/Article/EditLink/__snapshots__/index.stories.tsx.snap
@@ -1,7 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Article/EditLink Default smoke-test 1`] = `
-
    
+
    
   
     
       Edit this page on GitHub
diff --git a/components/Article/InlineCode/__snapshots__/index.stories.tsx.snap b/components/Article/InlineCode/__snapshots__/index.stories.tsx.snap
index 734dcbd2952be..793021fb1421b 100644
--- a/components/Article/InlineCode/__snapshots__/index.stories.tsx.snap
+++ b/components/Article/InlineCode/__snapshots__/index.stories.tsx.snap
@@ -1,7 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Article/InlineCode Default smoke-test 1`] = `
-
+
   
     const a = 1;
   
diff --git a/components/Blog/BlogCard/__snapshots__/index.stories.tsx.snap b/components/Blog/BlogCard/__snapshots__/index.stories.tsx.snap
index e19763764b8c1..edd7adfa14ace 100644
--- a/components/Blog/BlogCard/__snapshots__/index.stories.tsx.snap
+++ b/components/Blog/BlogCard/__snapshots__/index.stories.tsx.snap
@@ -1,15 +1,13 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Blog/BlogCard Default smoke-test 1`] = `
-
    
-  
    
+
    
+  
    
     
       Sample Test Blog
     
-    
    
-      
+    
    
+      
         category-mock
       
       
@@ -17,7 +15,7 @@ exports[`Blog/BlogCard Default smoke-test 1`] = `
       
     
    
   
    
-  
    
+  
    
     
    
       21 April 2023
     
    
diff --git a/components/Common/AnimatedPlaceholder/__snapshots__/index.stories.tsx.snap b/components/Common/AnimatedPlaceholder/__snapshots__/index.stories.tsx.snap
index 56afed2d696ce..5ae238eedf6d4 100644
--- a/components/Common/AnimatedPlaceholder/__snapshots__/index.stories.tsx.snap
+++ b/components/Common/AnimatedPlaceholder/__snapshots__/index.stories.tsx.snap
@@ -1,21 +1,21 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Common/AnimatedPlaceholder Default smoke-test 1`] = `
-
    
-  
    
+
    
+  
    
   
    
-  
    
-    
    
+  
    
+    
    
     
    
-    
    
+    
    
     
    
   
    
 
    
 `;
 
 exports[`Common/AnimatedPlaceholder WithLoaderSkeleton smoke-test 1`] = `
-
    
-  
    
+
    
+  
    
   
    
 
    
 `;
diff --git a/components/Common/Banner/__snapshots__/index.stories.tsx.snap b/components/Common/Banner/__snapshots__/index.stories.tsx.snap
index 1e4dbe587db95..2f0c316e29cd1 100644
--- a/components/Common/Banner/__snapshots__/index.stories.tsx.snap
+++ b/components/Common/Banner/__snapshots__/index.stories.tsx.snap
@@ -1,7 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Common/Banner WithHTML smoke-test 1`] = `
-