feat: parse CHANGELOG entry: and no-changelog

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Look for `CHANGELOG entry:` in the PR description, and look for `no-changelog` label, then apply this to the generated CHANGELOG, plus properly categorize by Conventional Commit type, including our custom ConventionalCommitType.RELEASE (#247)
+
 ## [5.0.2]
 
 ### Fixed

package.json

@@ -40,6 +40,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
+    "@octokit/rest": "^20.0.0",
     "diff": "^5.0.0",
     "execa": "^5.1.1",
     "semver": "^7.3.5",
@@ -56,6 +57,7 @@
     "@types/cross-spawn": "^6.0.2",
     "@types/diff": "^5.0.0",
     "@types/jest": "^26.0.23",
+    "@types/node": "^22.18.0",
     "@types/semver": "^7.3.6",
     "@types/yargs": "^16.0.1",
     "@typescript-eslint/eslint-plugin": "^5.42.1",

src/changelog.ts

@@ -107,12 +107,14 @@ type ChangelogChanges = Record<Version, ReleaseChanges> & {
  * @param category - The title of the changelog category.
  * @param changes - The changes included in this category.
  * @param repoUrl - The URL of the repository.
+ * @param useShortPrLink - Whether to use short PR links in the changelog entries.
  * @returns The stringified category section.
  */
 function stringifyCategory(
   category: ChangeCategory,
   changes: Change[],
   repoUrl: string,
+  useShortPrLink = false,
 ) {
   const categoryHeader = `### ${category}`;
   if (changes.length === 0) {
@@ -122,7 +124,11 @@ function stringifyCategory(
     .map(({ description, prNumbers }) => {
       const [firstLine, ...otherLines] = description.split('\n');
       const stringifiedPrLinks = prNumbers
-        .map((prNumber) => `[#${prNumber}](${repoUrl}/pull/${prNumber})`)
+        .map((prNumber) =>
+          useShortPrLink
+            ? `#${prNumber}`
+            : `[#${prNumber}](${repoUrl}/pull/${prNumber})`,
+        )
         .join(', ');
       const parenthesizedPrLinks =
         stringifiedPrLinks.length > 0 ? ` (${stringifiedPrLinks})` : '';
@@ -140,6 +146,7 @@ function stringifyCategory(
  * @param version - The release version.
  * @param categories - The categories of changes included in this release.
  * @param repoUrl - The URL of the repository.
+ * @param useShortPrLink - Whether to use short PR links in the changelog entries.
  * @param options - Additional release options.
  * @param options.date - The date of the release.
  * @param options.status - The status of the release (e.g., "DEPRECATED").
@@ -149,6 +156,7 @@ function stringifyRelease(
   version: Version | typeof unreleased,
   categories: ReleaseChanges,
   repoUrl: string,
+  useShortPrLink = false,
   { date, status }: Partial<ReleaseMetadata> = {},
 ) {
   const releaseHeader = `## [${version}]${date ? ` - ${date}` : ''}${
@@ -158,7 +166,7 @@ function stringifyRelease(
     .filter((category) => categories[category])
     .map((category) => {
       const changes = categories[category] ?? [];
-      return stringifyCategory(category, changes, repoUrl);
+      return stringifyCategory(category, changes, repoUrl, useShortPrLink);
     })
     .join('\n\n');
   if (categorizedChanges === '') {
@@ -173,21 +181,27 @@ function stringifyRelease(
  * @param releases - The releases to stringify.
  * @param changes - The set of changes to include, organized by release.
  * @param repoUrl - The URL of the repository.
+ * @param useShortPrLink - Whether to use short PR links in the changelog entries.
  * @returns The stringified set of release sections.
  */
 function stringifyReleases(
   releases: ReleaseMetadata[],
   changes: ChangelogChanges,
   repoUrl: string,
+  useShortPrLink = false,
 ) {
   const stringifiedUnreleased = stringifyRelease(
     unreleased,
     changes[unreleased],
     repoUrl,
+    useShortPrLink,
   );
   const stringifiedReleases = releases.map(({ version, date, status }) => {
     const categories = changes[version];
-    return stringifyRelease(version, categories, repoUrl, { date, status });
+    return stringifyRelease(version, categories, repoUrl, useShortPrLink, {
+      date,
+      status,
+    });
   });
 
   return [stringifiedUnreleased, ...stringifiedReleases].join('\n\n');
@@ -586,15 +600,22 @@ export default class Changelog {
    * Throws an error if no such release exists.
    *
    * @param version - The version of the release to stringify.
+   * @param useShortPrLink - Whether to use short PR links in the changelog entries.
    * @returns The stringified release, as it appears in the changelog.
    */
-  getStringifiedRelease(version: Version) {
+  getStringifiedRelease(version: Version, useShortPrLink = false) {
     const release = this.getRelease(version);
     if (!release) {
       throw new Error(`Specified release version does not exist: '${version}'`);
     }
     const releaseChanges = this.getReleaseChanges(version);
-    return stringifyRelease(version, releaseChanges, this.#repoUrl, release);
+    return stringifyRelease(
+      version,
+      releaseChanges,
+      this.#repoUrl,
+      useShortPrLink,
+      release,
+    );
   }
 
   /**
@@ -619,13 +640,14 @@ export default class Changelog {
   /**
    * The stringified changelog, formatted according to [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
    *
+   * @param useShortPrLink - Whether to use short PR links in the changelog entries.
    * @returns The stringified changelog.
    */
-  async toString(): Promise<string> {
+  async toString(useShortPrLink = false): Promise<string> {
     const changelog = `${changelogTitle}
 ${changelogDescription}
 
-${stringifyReleases(this.#releases, this.#changes, this.#repoUrl)}
+${stringifyReleases(this.#releases, this.#changes, this.#repoUrl, useShortPrLink)}
 
 ${stringifyLinkReferenceDefinitions(
   this.#repoUrl,

src/cli.ts

@@ -94,6 +94,14 @@ type UpdateOptions = {
    * The package rename properties, used in case of package is renamed
    */
   packageRename?: PackageRename;
+  /**
+   * Whether to use `CHANGELOG entry:` from the commit body and the no-changelog label
+   */
+  useChangelogEntry: boolean;
+  /**
+   * Whether to use short PR links in the changelog entries
+   */
+  useShortPrLink: boolean;
 };
 
 /**
@@ -107,9 +115,12 @@ type UpdateOptions = {
  * @param options.projectRootDirectory - The root project directory.
  * @param options.tagPrefix - The prefix used in tags before the version number.
  * @param options.formatter - A custom Markdown formatter to use.
- * @param options.packageRename - The package rename properties.
+ * @param options.packageRename - The package rename properties. Optional.
+ * Only needed when retrieving a changelog for a renamed package
+ * (e.g., utils -> @metamask/utils).
  * @param options.autoCategorize - Whether to categorize commits automatically based on their messages.
- * An optional, which is required only in case of package renamed.
+ * @param options.useChangelogEntry - Whether to read `CHANGELOG entry:` from the commit body and the no-changelog label.
+ * @param options.useShortPrLink - Whether to use short PR links in the changelog entries.
  */
 async function update({
   changelogPath,
@@ -121,6 +132,8 @@ async function update({
   formatter,
   packageRename,
   autoCategorize,
+  useChangelogEntry,
+  useShortPrLink,
 }: UpdateOptions) {
   const changelogContent = await readChangelog(changelogPath);
 
@@ -134,6 +147,8 @@ async function update({
     formatter,
     packageRename,
     autoCategorize,
+    useChangelogEntry,
+    useShortPrLink,
   });
 
   if (newChangelogContent) {
@@ -331,6 +346,17 @@ async function main() {
             description: `Expect the changelog to be formatted with Prettier.`,
             type: 'boolean',
           })
+          .option('useChangelogEntry', {
+            default: false,
+            description:
+              'Read `CHANGELOG entry:` from the commit body and the no-changelog label',
+            type: 'boolean',
+          })
+          .option('useShortPrLink', {
+            default: false,
+            description: 'Use short PR links in the changelog entries',
+            type: 'boolean',
+          })
           .epilog(updateEpilog),
     )
     .command(
@@ -388,6 +414,8 @@ async function main() {
     tagPrefixBeforePackageRename,
     autoCategorize,
     prLinks,
+    useChangelogEntry,
+    useShortPrLink,
   } = argv;
   let { currentVersion } = argv;
 
@@ -517,6 +545,8 @@ async function main() {
       formatter,
       packageRename,
       autoCategorize,
+      useChangelogEntry: Boolean(useChangelogEntry),
+      useShortPrLink: Boolean(useShortPrLink),
     });
   } else if (command === 'validate') {
     let packageRename: PackageRename | undefined;

src/constants.ts

@@ -7,15 +7,23 @@ export type Version = string;
  * A [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) type.
  */
 export enum ConventionalCommitType {
-  /**
-   * fix: a commit of the type fix patches a bug in your codebase
-   */
-  Fix = 'fix',
-  /**
-   * a commit of the type feat introduces a new feature to the codebase
-   */
-  Feat = 'feat',
+  FEAT = 'feat', // A new feature
+  FIX = 'fix', // A bug fix
+  DOCS = 'docs', // Documentation only changes
+  STYLE = 'style', // Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+  REFACTOR = 'refactor', // A code change that neither fixes a bug nor adds a feature
+  PERF = 'perf', // A code change that improves performance
+  TEST = 'test', // Adding missing tests or correcting existing tests
+  BUILD = 'build', // Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+  CI = 'ci', // Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+  CHORE = 'chore', // Other changes that don't modify src or test files (use this sparingly)
+  REVERT = 'revert', // Reverts a previous commit
+
+  // Custom types for MetaMask
+  BUMP = 'bump', // A version bump to dependencies
+  RELEASE = 'release', // A release commit, made on a release branch or to0 support the release process
 }
+
 /**
  * Change categories.
  *
@@ -58,6 +66,11 @@ export enum ChangeCategory {
    * For any changes that have yet to be categorized.
    */
   Uncategorized = 'Uncategorized',
+
+  /**
+   * For changes that should be excluded from the changelog.
+   */
+  Excluded = 'Excluded',
 }
 
 /**
@@ -78,3 +91,18 @@ export const orderedChangeCategories: ChangeCategory[] = [
  * The header for the section of the changelog listing unreleased changes.
  */
 export const unreleased = 'Unreleased';
+
+/**
+ * Lowercase keywords that indicate a commit should be excluded from the changelog.
+ */
+export const keywordsToIndicateExcluded: string[] = [
+  'Bump main version to',
+  'changelog',
+  'cherry-pick',
+  'cp-',
+  'e2e',
+  'flaky test',
+  'INFRA-',
+  'merge',
+  'New Crowdin translations',
+].map((word) => word.toLowerCase());