build: add workflow to generate monthly changelog

PR-URL: #5983
Closes: stdlib-js/metr-issue-tracker#6
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]>

Author: Planeshifter

.github/workflows/generate_monthly_changelog.yml

@@ -0,0 +1,138 @@
+#/
+# @license Apache-2.0
+#
+# Copyright (c) 2025 The Stdlib Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#/
+
+# Workflow name:
+name: generate_monthly_changelog
+
+# Workflow triggers:
+on:
+  # Run the workflow at midnight UTC on the first day of each month:
+  schedule:
+    - cron: '0 0 1 * *'
+
+  # Allow the workflow to be manually run:
+  workflow_dispatch:
+
+# Global permissions:
+permissions:
+  # Allow read-only access to the repository contents:
+  contents: read
+
+# Workflow jobs:
+jobs:
+  # Generate a monthly changelog:
+  generate-monthly-changelog:
+    # Define a display name:
+    name: 'Generate Monthly Changelog'
+
+    # Define the type of virtual host machine:
+    runs-on: ubuntu-latest
+
+    # Workflow steps:
+    steps:
+      - name: 'Checkout source repository'
+        # Pin action to full length commit SHA
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          # Specify whether to remove untracked files before checking out the repository:
+          clean: false
+
+          # Limit clone depth to the most recent commit:
+          fetch-depth: 1
+
+          # Token for accessing the repository:
+          token: ${{ secrets.STDLIB_BOT_FGPAT_REPO_READ }}
+
+          # Avoid storing GitHub token in local Git configuration:
+          persist-credentials: false
+
+      # Install Node.js:
+      - name: 'Install Node.js'
+        # Pin action to full length commit SHA
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+        with:
+          node-version: '20' # 'lts/*'
+        timeout-minutes: 5
+
+      # Install dependencies (accounting for possible network failures, etc, when installing node module dependencies):
+      - name: 'Install dependencies'
+        run: |
+          make install-node-modules || make install-node-modules || make install-node-modules
+        timeout-minutes: 15
+
+      - name: 'Checkout monthly changelog repository'
+        # Pin action to full length commit SHA
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          # Monthly changelog repository:
+          repository: 'stdlib-js/www-blog-monthly-changelog'
+
+          # File path to checkout to:
+          path: './www-blog-monthly-changelog'
+
+          # Specify whether to remove untracked files before checking out the repository:
+          clean: false
+
+          # Limit clone depth to the most recent commit:
+          fetch-depth: 1
+
+          # Token for accessing the repository:
+          token: ${{ secrets.STDLIB_BOT_FGPAT_REPO_READ }}
+
+          # Avoid storing GitHub token in local Git configuration:
+          persist-credentials: false
+
+      # Generate changelog for last month:
+      - name: 'Generate changelog for last month'
+        run: |
+          UNTIL=$(date +"%Y-%m-01")
+          node -e "
+          var generate = require( '@stdlib/_tools/changelog/generate' );
+          var changelog = generate( '@stdlib', {
+            'flags': {
+              'since': '$UNTIL - 1 month',
+              'until': '$UNTIL'
+            },
+            'format': 'aggregated'
+          });
+          console.log( changelog.content );
+
+          " > ./www-blog-monthly-changelog/monthly_changelog_${UNTIL//-/_}.md
+
+      # Import GPG key to sign commits:
+      - name: 'Import GPG key to sign commits'
+        # Pin action to full length commit SHA
+        uses: crazy-max/ghaction-import-gpg@cb9bde2e2525e640591a934b1fd28eef1dcaf5e5 # v6.2.0
+        with:
+          gpg_private_key: ${{ secrets.STDLIB_BOT_GPG_PRIVATE_KEY }}
+          passphrase: ${{ secrets.STDLIB_BOT_GPG_PASSPHRASE }}
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+
+      # Commit and push changes:
+      - name: 'Commit and push changes'
+        env:
+          REPO_GITHUB_TOKEN: ${{ secrets.STDLIB_BOT_PAT_REPO_WRITE }}
+          USER_NAME: stdlib-bot
+        run: |
+          cd ./www-blog-monthly-changelog
+          git config --local user.email "[email protected]"
+          git config --local user.name "stdlib-bot"
+          git add .
+          git commit -m "Add monthly changelog" || exit 0
+          git push "https://$USER_NAME:[email protected]/stdlib-js/www-blog-monthly-changelog.git" main

lib/node_modules/@stdlib/_tools/changelog/generate/README.md

@@ -30,10 +30,12 @@ limitations under the License.
 var generate = require( '@stdlib/_tools/changelog/generate' );
 ```
 
-#### generate( pkg\[, releaseType] )
+#### generate( pkg\[, options] )
 
 Generates a Markdown formatted changelog for a specified package.
 
+<!-- run-disable -->
+
 ```javascript
 var changelog = generate( '@stdlib/assert/contains' );
 // returns {...}
@@ -44,13 +46,30 @@ The function returns an object with the following properties:
 -   **content**: Markdown formatted changelog.
 -   **releaseType**: release type (`null` if changelog is for a non-release).
 
-To generate a changelog for an upcoming release, provide a valid release type as the second argument.
+The function accepts the following `options`:
+
+-   **releaseType**: a release type for which to generate the changelog.
+
+-   **format**: changelog format. Must be one of the following:
+
+    -   `'grouped'`: group commits by package.
+    -   `'aggregated'`: display all commits in a flat list without grouping commits by package.
+
+-   **flags**: `git log` options used to retrieve commits from which to generate the changelog.
+
+By default, the changelog is generated for a non-release. To generate a changelog for an upcoming release, provide a valid release type:
+
+<!-- run-disable -->
 
 ```javascript
-var changelog = generate( '@stdlib/assert/contains', 'patch' );
+var changelog = generate( '@stdlib/assert/contains', {
+    'releaseType': 'patch'
+});
 // returns {...}
 
-changelog = generate( '@stdlib/assert/contains', 'minor' );
+changelog = generate( '@stdlib/assert/contains', {
+    'releaseType': 'minor'
+});
 // returns {...}
 ```
 
@@ -66,6 +85,44 @@ The following release types are supported:
 -   `auto`: automatically determine the release type based on parsed commit messages.
 -   `none`: no release (equivalent to not specifying a release type).
 
+By default, the function generates a `grouped` changelog for namespace packages and an `aggregated` changelog for non-namespace packages. To specify a desired output format, set the `format` option:
+
+<!-- run-disable -->
+
+```javascript
+// Changelog grouped by individual packages:
+var changelog = generate( '@stdlib/math/base/utils', {
+    'format': 'grouped'
+});
+// returns {...}
+
+// Changelog where all commits, potentially touching many different packages, are merged together:
+changelog = generate( '@stdlib/math/base/utils', {
+    'format': 'aggregated'
+});
+// returns {...}
+```
+
+When generating a changelog, the function uses `git log` to retrieve the commits from which to assemble a set of changes. The `flags` option allows passing options to directly to the `git log` command (e.g., to generate a changelog for a specified time interval or for an individual contributor).
+
+<!-- run-disable -->
+
+```javascript
+var changelog = generate( '@stdlib/ndarray', {
+    'flags': {
+        'since': 'last year'
+    }
+});
+// returns {...}
+
+changelog = generate( '@stdlib/ndarray', {
+    'flags': {
+        'author': 'Athan Reines <[email protected]>'
+    }
+});
+// returns {...}
+```
+
 </section>
 
 <!-- /.usage -->
@@ -80,6 +137,8 @@ The following release types are supported:
 
 ## Examples
 
+<!-- run-disable -->
+
 ```javascript
 var generate = require( '@stdlib/_tools/changelog/generate' );
 
@@ -92,7 +151,9 @@ var releaseType = changelog.releaseType;
 // returns null
 
 // Generate a changelog for a new release:
-changelog = generate( '@stdlib/utils/curry', 'patch' );
+changelog = generate( '@stdlib/utils/curry', {
+    'releaseType': 'patch'
+});
 content = changelog.content;
 // returns '...'
 
@@ -103,6 +164,15 @@ releaseType = changelog.releaseType;
 changelog = generate( '@stdlib/string/base' );
 content = changelog.content;
 // returns '...'
+
+// Generate a changelog restricted to a single author:
+changelog = generate( '@stdlib/string/base', {
+    'flags': {
+        'author': 'Athan Reines <[email protected]>'
+    }
+});
+content = changelog.content;
+// returns '...'
 ```
 
 </section>

lib/node_modules/@stdlib/_tools/changelog/generate/examples/index.js

@@ -31,7 +31,9 @@ console.log( releaseType );
 // => null
 
 // Generate a changelog for a new release:
-changelog = generate( '@stdlib/utils/curry', 'patch' );
+changelog = generate( '@stdlib/utils/curry', {
+	'releaseType': 'patch'
+});
 content = changelog.content;
 console.log( content );
 // => '...'
@@ -45,3 +47,12 @@ changelog = generate( '@stdlib/string/base' );
 content = changelog.content;
 console.log( content );
 // => '...'
+
+// Generate a changelog restricted to a single author:
+changelog = generate( '@stdlib/string/base', {
+	'flags': {
+		'author': 'Athan Reines <[email protected]>'
+	}
+});
+content = changelog.content;
+console.log( content );