[release notes] Add new frontmatter for the indexer (#1985)

* chore: add new frontmatter * feat: attempt to make type backwards compatible * fix: typo * chore: add some documentation * chore: add changeset * feat: display multiple types * refactor: change type of new frontmatters * chore: add logs to analyse error * refactor: adjust documentation * chore: improve logs * chore: fix build error * feat: add new deprecation release note type --------- Co-authored-by: FFawzy <[email protected]> Co-authored-by: Gabriele Antonini <[email protected]>
commercetools · May 27, 2024 · dc1bdf3 · dc1bdf3
1 parent 49e9d0a
commit dc1bdf3
Show file tree

Hide file tree

Showing 9 changed files with 122 additions and 54 deletions.
diff --git a/.changeset/popular-needles-join.md b/.changeset/popular-needles-join.md
@@ -0,0 +1,6 @@
+---
+'@commercetools-docs/gatsby-theme-docs': minor
+---
+
+Introduce two new frontmatter for release notes called "product" and "productArea".
+It also introduces a new release note type called "deprecation".
diff --git a/packages/gatsby-theme-docs/gatsby-node.mjs b/packages/gatsby-theme-docs/gatsby-node.mjs
@@ -118,6 +118,18 @@ export const createResolvers = ({ createResolvers }) => {
         },
       },
     },
+    ReleaseNotePage: {
+      type: {
+        resolve: (source) => {
+          if (Array.isArray(source.type)) {
+            return source.type;
+          } else if (typeof source.type === 'string') {
+            return [source.type];
+          }
+          return [];
+        },
+      },
+    },
   };
   createResolvers(resolvers);
 };
@@ -221,6 +233,7 @@ export const createSchemaCustomization = ({ actions, schema }) => {
       fix
       enhancement
       announcement
+      deprecation
     }
   `);
 
@@ -299,7 +312,9 @@ export const createSchemaCustomization = ({ actions, schema }) => {
         date: { type: 'Date!', extensions: { dateformat: {} } },
         orderHint: { type: 'Int' },
         description: { type: 'String!' },
-        type: { type: 'ReleaseNoteType!' },
+        type: { type: '[ReleaseNoteType!]!' },
+        product: { type: 'String' },
+        productArea: { type: 'String' },
         topics: { type: '[String!]!' },
         published: { type: 'Boolean!' },
         body: {
@@ -359,6 +374,8 @@ export const onCreateNode = async (
       orderHint: node.frontmatter.orderHint,
       description: node.frontmatter.description,
       type: node.frontmatter.type,
+      product: node.frontmatter.product,
+      productArea: node.frontmatter.productArea,
       topics: node.frontmatter.topics || [],
       published: Boolean(node.frontmatter.published),
       rawExcerpt: excerptSplit[0],

diff --git a/packages/gatsby-theme-docs/src/layouts/internals/layout-release-note-body.js b/packages/gatsby-theme-docs/src/layouts/internals/layout-release-note-body.js
@@ -20,76 +20,88 @@ const Topics = styled.div`
   }
 `;
 
-const ReleaseNoteBody = (props) => (
-  <SpacingsStack scale="m">
-    <SpacingsStack scale="s">
-      <DateElement>{props.date}</DateElement>
-      <div
-        style={designSystem.tokensToCssVars({
-          fontSizeDefault: designSystem.typography.fontSizes.extraSmall,
-          fontSizeForStamp: designSystem.typography.fontSizes.extraSmall,
-          // Override the `critical` style which is used for the "fix" type
-          colorError95: designSystem.colors.light.surfaceForReleaseNoteTypeFix,
-          colorError: designSystem.colors.light.borderForReleaseNoteTypeFix,
-        })}
-      >
-        <SpacingsInline>
-          <Stamp
-            isCondensed
-            tone={mapTypeToTone(props)}
-            label={mapTypeToLabel(props)}
-          />
-        </SpacingsInline>
-      </div>
-      {props.topics.length > 0 && (
-        <Topics>
-          {props.topics.map((topic) => (
-            <span key={topic}>{topic}</span>
-          ))}
-        </Topics>
-      )}
+const ReleaseNoteBody = (props) => {
+  const releaseNoteType = Array.isArray(props.type) ? props.type : [props.type];
+  return (
+    <SpacingsStack scale="m">
+      <SpacingsStack scale="s">
+        <DateElement>{props.date}</DateElement>
+        <div
+          style={designSystem.tokensToCssVars({
+            fontSizeDefault: designSystem.typography.fontSizes.extraSmall,
+            fontSizeForStamp: designSystem.typography.fontSizes.extraSmall,
+            // Override the `critical` style which is used for the "fix" type
+            colorError95:
+              designSystem.colors.light.surfaceForReleaseNoteTypeFix,
+            colorError: designSystem.colors.light.borderForReleaseNoteTypeFix,
+          })}
+        >
+          <SpacingsInline>
+            {releaseNoteType.map((type) => {
+              return (
+                <Stamp
+                  key={type}
+                  isCondensed
+                  tone={mapTypeToTone(type)}
+                  label={mapTypeToLabel(type)}
+                />
+              );
+            })}
+          </SpacingsInline>
+        </div>
+        {props.topics.length > 0 && (
+          <Topics>
+            {props.topics.map((topic) => (
+              <span key={topic}>{topic}</span>
+            ))}
+          </Topics>
+        )}
+      </SpacingsStack>
+      <div>{props.children}</div>
     </SpacingsStack>
-    <div>{props.children}</div>
-  </SpacingsStack>
-);
+  );
+};
 
 ReleaseNoteBody.propTypes = {
   date: PropTypes.string.isRequired,
   // eslint-disable-next-line react/no-unused-prop-types
-  type: PropTypes.oneOf(['feature', 'enhancement', 'fix', 'announcement'])
-    .isRequired,
+  type: PropTypes.arrayOf(PropTypes.string.isRequired).isRequired,
   topics: PropTypes.arrayOf(PropTypes.string.isRequired).isRequired,
   children: PropTypes.node.isRequired,
 };
 
 export default ReleaseNoteBody;
 
-function mapTypeToTone(props) {
-  switch (props.type) {
+function mapTypeToTone(type) {
+  switch (type) {
     case 'feature':
-      return 'positive';
+      return 'primary';
     case 'enhancement':
-      return 'information';
+      return 'positive';
     case 'fix':
       return 'positive';
     case 'announcement':
-      return 'primary';
+      return 'information';
+    case 'deprecation':
+      return 'secondary';
     default:
-      return props.type;
+      return type;
   }
 }
 
-function mapTypeToLabel(props) {
-  switch (props.type) {
+function mapTypeToLabel(type) {
+  switch (type) {
     case 'feature':
-      return 'Feature';
+      return 'New feature';
     case 'enhancement':
       return 'Enhancement';
     case 'fix':
-      return 'Resolved Issue';
+      return 'Resolved issue';
     case 'announcement':
       return 'Announcement';
+    case 'deprecation':
+      return 'Deprecation';
     default:
-      return props.type;
+      return type;
   }
 }
diff --git a/packages/gatsby-theme-docs/src/layouts/internals/layout-release-note.js b/packages/gatsby-theme-docs/src/layouts/internals/layout-release-note.js
@@ -34,8 +34,7 @@ LayoutReleaseNote.propTypes = {
   title: PropTypes.string.isRequired,
   date: PropTypes.string.isRequired,
   description: PropTypes.string.isRequired,
-  type: PropTypes.oneOf(['feature', 'enhancement', 'fix', 'announcement'])
-    .isRequired,
+  type: PropTypes.arrayOf(PropTypes.string.isRequired).isRequired,
   topics: PropTypes.arrayOf(PropTypes.string.isRequired).isRequired,
   hasMore: PropTypes.bool.isRequired,
   children: PropTypes.node.isRequired,

diff --git a/packages/gatsby-theme-docs/src/templates/release-notes-list.js b/packages/gatsby-theme-docs/src/templates/release-notes-list.js
@@ -75,7 +75,7 @@ ReleaseNotesListTemplate.propTypes = {
           title: PropTypes.string.isRequired,
           date: PropTypes.string.isRequired,
           description: PropTypes.string.isRequired,
-          type: PropTypes.string.isRequired,
+          type: PropTypes.arrayOf(PropTypes.string.isRequired).isRequired,
           topics: PropTypes.arrayOf(PropTypes.string.isRequired).isRequired,
           body: PropTypes.string.isRequired,
           hasMore: PropTypes.bool.isRequired,
@@ -124,6 +124,8 @@ export const query = graphql`
         orderHint
         description
         type
+        product
+        productArea
         topics
         body: rawExcerpt
         hasMore

diff --git a/websites/docs-smoke-test/src/releases/release-format-definition.mdx b/websites/docs-smoke-test/src/releases/release-format-definition.mdx
@@ -4,7 +4,7 @@ title: Release Note Format Definition
 description: |
   The description must be a stand-alone text conveying the key change and its advantages for external feed consumers,
   redistribution, notifications and others.
-type: feature # feature | fix | enhancement | announcement
+type: feature # feature | fix | enhancement | announcement | deprecation
 topics: # see topic examples below
   - Carts
   - Customers

diff --git a/websites/docs-smoke-test/src/releases/release-note-template.mdx b/websites/docs-smoke-test/src/releases/release-note-template.mdx
@@ -1,9 +1,10 @@
 ---
 date: 2020-01-01
 title: (TEMPLATE) TITLE
-description: | # title content and what this is good for //  max 256 characters // for MC, RSS and other feeds
+description:
+  | # title content and what this is good for //  max 256 characters // for MC, RSS and other feeds
   (TEMPLATE) DESCRIPTION
-type: enhancement # feature | fix | enhancement | announcement
+type: enhancement # feature | fix | enhancement | announcement | deprecation
 topics:
 # uncomment matching topics. Stay focused.
 #  - Products
@@ -16,7 +17,7 @@ topics:
 
 FooBar Intro Line: What this is good for (like description)
 
- * [API] FooBar
+- [API] FooBar
 
 <!--more-->
 

diff --git a/websites/docs-smoke-test/src/releases/release-note-with-index-frontmatters.mdx b/websites/docs-smoke-test/src/releases/release-note-with-index-frontmatters.mdx
@@ -0,0 +1,25 @@
+---
+date: 2024-05-21
+title: Release note with index frontmatters
+description: |
+  Release note for testing frontmatters that are being used at the release note indexer
+type:
+  - announcement
+  - fix
+  - enhancement
+  - feature
+  - deprecation
+topics:
+  - Settings
+product: Composable Commerce
+productArea: HTTP APIs
+---
+
+FooBar Intro Line: What this is good for (like description)
+
+- [API] FooBar
+
+<!--more-->
+
+A longer explanation here that is just shown on the details page.
+If there is no more, remove the marker above, too.
diff --git a/websites/documentation/src/content/writing/release-notes.mdx b/websites/documentation/src/content/writing/release-notes.mdx
@@ -65,7 +65,13 @@ If there is no more, remove the marker above, too.
 - `title` (string, required): The title for the website
 - `description` (string, required): Max 256 characters plain text containing the change and its advantage ("tweet-able" and for RSS).
   256 = 280 twitter minus 23 for a link. Do not imply the title, this text is used stand-alone in Merchant Center and other feed recipients. It must convey the value proposition and key change topic.
-- `type` (string, optional): Must be either `feature` (for "New Feature"), `fix` (for "Resolved Issue") or `enhancement` (for "Enhancement")
+- `type` (string | string[], required): Must be either `feature` (for "New Feature"), `fix` (for "Resolved Issue") or `enhancement` (for "Enhancement")
 - `topics` (array of string, optional): YAML array of free to choose text entries. The Filter UI may be constrained to pre-defined topics.
 - `published` (boolean, optional, defaults to `true`): `false` prevents rendering of the release in the site. **Should not be used in the main documentation**, reserved for atypical situations. Not included in the template.
-- `slug` (string, optional, defaults to `$date-$title` (slugified)): optional, allows overriding the autogenerated URL slug. **Should not be used in the main documentation**, reserved for migrating legacy docs.
+- `slug` (string, optional, defaults to `$date-$title` (slugified)): Allows overriding the autogenerated URL slug. **Should not be used in the main documentation**, reserved for migrating legacy docs.
+- `product` (string, optional): Used in the release notes search to filter by product. If set, it overrides the `product` defined in the website `gatsby-configure.mjs`. Please note that in case an array is defined, just the first value is used for filtering purposes.
+- `productArea` (string, optional): Used in the release notes search to filter by product area. If set, it overrides the `title` defined in the website `gatsby-configure.mjs`.
+
+## Release note's search indexing
+
+Each time a feature branch containing changes to any file existing in the website's `releases` directory is merged into main, it will trigger a full reindex of all the release notes.