build: add tooling for changelog generation

.github/workflows/standalone_publish.yml

@@ -33,6 +33,7 @@ on:
         - patch
         - minor
         - major
+        - auto
       dry-run:
         type: boolean
         description: 'Skip uploading packages (dry run):'

.github/workflows/standalone_publish_custom.yml

@@ -48,6 +48,7 @@ on:
         - patch
         - minor
         - major
+        - auto
       only-unpublished:
         type: boolean
         description: 'Only publish packages that have not yet been published'

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

@@ -0,0 +1,49 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 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.
+
+-->
+
+# Changelog
+
+> Changelog tooling.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+This directory contains utilities for managing and maintaining changelogs of project packages.
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+</section>
+
+<!-- /.links -->

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

@@ -0,0 +1,125 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 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.
+
+-->
+
+# Generate Changelog
+
+> Generate a changelog for a specified stdlib package.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var generate = require( '@stdlib/_tools/changelog/generate' );
+```
+
+#### generate( pkg\[, releaseType] )
+
+Generates a Markdown formatted changelog for a specified package.
+
+```javascript
+var changelog = generate( '@stdlib/assert/contains' );
+// returns {...}
+```
+
+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.
+
+```javascript
+var changelog = generate( '@stdlib/assert/contains', 'patch' );
+// returns {...}
+
+changelog = generate( '@stdlib/assert/contains', 'minor' );
+// returns {...}
+```
+
+The following release types are supported:
+
+-   `patch`: a patch release (e.g., bug fixes).
+-   `minor`: a minor release (e.g., new features which do not break backward compatibility).
+-   `major`: a major release (e.g., breaking changes).
+-   `prerelease`: a prerelease (e.g., a release candidate).
+-   `prepatch`: a prepatch release.
+-   `preminor`: a preminor release.
+-   `premajor`: a premajor release.
+-   `auto`: automatically determine the release type based on parsed commit messages.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+```javascript
+var generate = require( '@stdlib/_tools/changelog/generate' );
+
+// Generate a changelog for a non-namespace package:
+var changelog = generate( '@stdlib/utils/curry' );
+var content = changelog.content;
+// returns '...'
+
+var releaseType = changelog.releaseType;
+// returns null
+
+// Generate a changelog for a new release:
+changelog = generate( '@stdlib/utils/curry', 'patch' );
+content = changelog.content;
+// returns '...'
+
+releaseType = changelog.releaseType;
+// returns 'patch'
+
+// Generate a changelog for a namespace package:
+changelog = generate( '@stdlib/string/base' );
+content = changelog.content;
+// returns '...'
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+</section>
+
+<!-- /.links -->

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

@@ -0,0 +1,47 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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.
+*/
+
+'use strict';
+
+var generate = require( './../lib' );
+
+// Generate a changelog for a non-namespace package:
+var changelog = generate( '@stdlib/utils/curry' );
+var content = changelog.content;
+console.log( content );
+// => '...'
+
+var releaseType = changelog.releaseType;
+console.log( releaseType );
+// => null
+
+// Generate a changelog for a new release:
+changelog = generate( '@stdlib/utils/curry', 'patch' );
+content = changelog.content;
+console.log( content );
+// => '...'
+
+releaseType = changelog.releaseType;
+console.log( releaseType );
+// => 'patch'
+
+// Generate a changelog for a namespace package:
+changelog = generate( '@stdlib/string/base' );
+content = changelog.content;
+console.log( content );
+// => '...'

lib/node_modules/@stdlib/_tools/changelog/generate/lib/breaking_changes.js

@@ -0,0 +1,110 @@
+
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var filter = require( '@stdlib/array/base/filter' );
+var trim = require( '@stdlib/string/trim' );
+var map = require( '@stdlib/utils/map' );
+var collectField = require( './collect_field.js' );
+var sectionStart = require( './section_start.js' );
+var sectionEnd = require( './section_end.js' );
+var heading = require( './heading.js' );
+
+
+// VARIABLES //
+
+var STDLIB_GITHUB_URL = 'https://github.com/stdlib-js/stdlib/commit';
+
+
+// FUNCTIONS //
+
+/**
+* Formats a breaking change.
+*
+* @private
+* @param {Object} note - note object
+* @returns {string} changelog entry
+*
+* @example
+* var note = {
+*     'title': 'BREAKING CHANGE',
+*     'text': 'beep',
+*     'hash': 'abcdef1234567890'
+* };
+* var out = formatBreakingChange( note );
+* // returns '-   [`abcdef1`](https://github.com/stdlib-js/stdlib/commit/abcdef1234567890): beep'
+*/
+function formatBreakingChange( note ) {
+	var parts = note.text.split( '\n' );
+	var hash = trim( note.hash );
+	var out = '-   [`'+hash.substring( 0, 7 )+'`]('+STDLIB_GITHUB_URL+'/'+hash+'): '+parts[ 0 ];
+	if ( parts.length > 1 ) {
+		out +=' \n\n';
+		out += '    -   ';
+		out += parts.slice( 1 ).join( '\n    ' );
+		out += '\n';
+	}
+	return out;
+}
+
+/**
+* Tests whether a note is a breaking change.
+*
+* @private
+* @param {Object} note - note object
+* @returns {boolean} boolean indicating whether a note is a breaking change
+*/
+function isBreakingChange( note ) {
+	return note.title === 'BREAKING CHANGE';
+}
+
+
+// MAIN //
+
+/**
+* Extracts breaking changes from a list of commits and formats them as a Markdown list.
+*
+* @private
+* @param {ObjectArray} commits - commit objects
+* @returns {string} list of breaking changes
+*/
+function breakingChanges( commits ) {
+	var breakingChanges;
+	var notes;
+	var out;
+
+	notes = collectField( commits, 'notes' );
+	breakingChanges = filter( notes, isBreakingChange );
+	if ( breakingChanges.length === 0 ) {
+		return '';
+	}
+	out = sectionStart( 'breaking-changes' );
+	out += heading( 'BREAKING CHANGES', 3 );
+	out += map( breakingChanges, formatBreakingChange ).join( '\n' );
+	out += sectionEnd( 'breaking-changes' );
+	return out;
+}
+
+
+// EXPORTS //
+
+module.exports = breakingChanges;