build: add format option to changelog generation

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

---
type: pre_push_report
description: Results of running various checks prior to pushing changes.
report:
  - task: run_javascript_examples
    status: na
  - task: run_c_examples
    status: na
  - task: run_cpp_examples
    status: na
  - task: run_javascript_readme_examples
    status: failed
---

Author: Planeshifter

.github/workflows/generate_monthly_changelog.yml

@@ -107,7 +107,8 @@ jobs:
             'flags': {
               'since': '$UNTIL - 1 week',
               'until': '$UNTIL'
-            }
+            },
+            'format': 'aggregated'
           });
           console.log( changelog.content );
           " > ./www-blog-monthly-changelog/monthly_changelog_$UNTIL.md

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

@@ -47,6 +47,7 @@ The function returns an object with the following properties:
 The function accepts the following `options`:
 
 -   **releaseType**: a release type for which to generate the changelog.
+-   **format**: whether to generate a `grouped` changelog where commits are grouped by package or `aggregated` one.
 -   **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:
@@ -75,8 +76,26 @@ 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:
+
+```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).
 
+<!-- eslint-disable stdlib/doctest -->
+
 ```javascript
 var changelog = generate( '@stdlib/ndarray', {
     'flags': {

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

@@ -211,6 +211,7 @@ function packageSummaryWrapper( pkg, version, name, summary ) {
 * @param {string} pkg - package name
 * @param {Options} options - function options
 * @param {string} [options.releaseType] - release type (`patch`, `minor`, `major`, `prerelease`, `prepatch`, `preminor`, `premajor`, or `auto`)
+* @param {string} [options.format] - output format (`grouped` or `aggregated`)
 * @param {Options} [options.flags] - `git log` options used to retrieve commits
 * @throws {TypeError} must provide a string
 * @throws {Error} must provide a valid package name
@@ -245,6 +246,7 @@ function generate( pkg, options ) {
 	var isNamespacePkg;
 	var releaseCommits;
 	var newestRelease;
+	var outputFormat;
 	var bySubpackage;
 	var releaseType;
 	var nextVersion;
@@ -272,6 +274,10 @@ function generate( pkg, options ) {
 			throw err;
 		}
 	}
+	outputFormat = opts.format;
+	if ( !outputFormat ) {
+		outputFormat = ( isNamespacePkg ) ? 'grouped' : 'aggregated';
+	}
 
 	if ( pkg === '@stdlib' || pkg === '@stdlib/stdlib' ) {
 		// Case: root package
@@ -341,7 +347,7 @@ function generate( pkg, options ) {
 		}
 	}
 
-	if ( isNamespacePkg && !opts.flags ) {
+	if ( outputFormat === 'grouped' ) {
 		str += releaseSectionStart( nextVersion );
 		str += '## ' + ( nextVersion || 'Unreleased' ) + ' (' + formatDate() + ')\n\n';
 		if ( commits.unreleased.length > 0 ) {
@@ -374,7 +380,7 @@ function generate( pkg, options ) {
 			str += sectionEnd( 'release' );
 		}
 	}
-	if ( isNamespacePkg && !opts.flags ) {
+	if ( outputFormat === 'grouped' ) {
 		for ( i = releases.length-1; i >= 0; i-- ) {
 			version = releases[ i ][ 0 ];
 			str += releaseSectionStart( version );

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

@@ -24,9 +24,15 @@ var isObject = require( '@stdlib/assert/is-plain-object' );
 var hasOwnProp = require( '@stdlib/assert/has-own-property' );
 var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
 var isPlainObject = require( '@stdlib/assert/is-plain-object' );
+var indexOf = require( '@stdlib/utils/index-of' );
 var format = require( '@stdlib/string/format' );
 
 
+// VARIABLES //
+
+var FORMAT_OPTIONS = [ 'grouped', 'aggregated' ];
+
+
 // MAIN //
 
 /**
@@ -36,6 +42,7 @@ var format = require( '@stdlib/string/format' );
 * @param {Object} opts - destination for function options
 * @param {Options} options - function options
 * @param {string} [options.releaseType] - release type
+* @param {string} [options.format] - output format (`grouped` or `aggregated`)
 * @param {string} [options.flags] - `git log` options used to retrieve commits
 * @returns {(Error|null)} error or null
 *
@@ -59,6 +66,12 @@ function validate( opts, options ) {
 			return new TypeError( format( 'invalid option. `%s` option must be a string. Option: `%s`.', 'releaseType', opts.releaseType ) );
 		}
 	}
+	if ( hasOwnProp( options, 'format' ) ) {
+		opts.format = options.format;
+		if ( indexOf( FORMAT_OPTIONS, opts.format ) === -1 ) {
+			return new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Option: `%s`.', 'format', FORMAT_OPTIONS.join( '", "' ), opts.format ) );
+		}
+	}
 	if ( hasOwnProp( options, 'flags' ) ) {
 		opts.flags = options.flags;
 		if ( !isPlainObject( opts.flags ) ) {

lib/node_modules/@stdlib/_tools/changelog/generate/test/test.validate.js

@@ -80,6 +80,32 @@ tape( 'the function returns an error if provided a `releaseType` option which is
 	t.end();
 });
 
+tape( 'the function returns an error if provided a `format` option which is not a recognized format option', function test( t ) {
+	var values;
+	var err;
+	var i;
+
+	values = [
+		true,
+		5,
+		NaN,
+		null,
+		void 0,
+		{},
+		[],
+		function noop() {},
+		'abc'
+	];
+
+	for ( i = 0; i < values.length; i++ ) {
+		err = validate( {}, {
+			'format': values[ i ]
+		});
+		t.ok( err instanceof TypeError, 'returns a type error when provided ' + values[ i ] );
+	}
+	t.end();
+});
+
 tape( 'the function returns an error if provided a `flags` option which is not an object', function test( t ) {
 	var values;
 	var err;
@@ -111,7 +137,8 @@ tape( 'the function returns `null` if all options are valid', function test( t )
 	var obj;
 
 	opts = {
-		'releaseType': 'auto'
+		'releaseType': 'auto',
+		'format': 'grouped'
 	};
 	obj = {};
 	err = validate( obj, opts );