feat(options): adds changelogTitle option

README.md

@@ -21,9 +21,11 @@ Create or update the changelog file in the local project repository.
 
 ### Options
 
-| Options         | Description                 | Default        |
-|-----------------|-----------------------------|----------------|
-| `changelogFile` | File path of the changelog. | `CHANGELOG.md` |
+| Options          | Description                 | Default        |
+|------------------|-----------------------------|----------------|
+| `changelogFile`  | File path of the changelog. | `CHANGELOG.md` |
+| `changelogTitle` | Title in the changelog.     | None           |
+
 
 ### Usage
 

lib/definitions/errors.js

@@ -13,4 +13,12 @@ module.exports = {
 
 Your configuration for the \`changelogFile\` option is \`${changelogFile}\`.`,
   }),
+  EINVALIDCHANGELOGTITLE: ({changelogTitle}) => ({
+    message: 'Invalid `changelogTitle` option.',
+    details: `The [changelogTitle option](${linkify(
+      'README.md#options'
+    )}) option, if defined, must be a non empty \`String\`.
+
+Your configuration for the \`changelogTitle\` option is \`${changelogTitle}\`.`,
+  }),
 };

lib/prepare.js

@@ -2,7 +2,7 @@ const {readFile, writeFile, ensureFile} = require('fs-extra');
 const resolveConfig = require('./resolve-config');
 
 module.exports = async (pluginConfig, notes, logger) => {
-  const {changelogFile} = resolveConfig(pluginConfig);
+  const {changelogFile, changelogTitle} = resolveConfig(pluginConfig);
 
   if (notes) {
     await ensureFile(changelogFile);
@@ -13,6 +13,13 @@ module.exports = async (pluginConfig, notes, logger) => {
     } else {
       logger.log('Create %s', changelogFile);
     }
-    await writeFile(changelogFile, `${notes.trim()}\n${currentFile ? `\n${currentFile}\n` : ''}`);
+
+    const currentContent =
+      changelogTitle && currentFile.startsWith(changelogTitle)
+        ? currentFile.slice(changelogTitle.length).trim()
+        : currentFile;
+    const content = `${notes.trim()}\n${currentContent ? `\n${currentContent}\n` : ''}`;
+
+    await writeFile(changelogFile, changelogTitle ? `${changelogTitle}\n\n${content}` : content);
   }
 };

lib/resolve-config.js

@@ -1,5 +1,6 @@
 const {isUndefined} = require('lodash');
 
-module.exports = ({changelogFile}) => ({
+module.exports = ({changelogFile, changelogTitle}) => ({
   changelogFile: isUndefined(changelogFile) ? 'CHANGELOG.md' : changelogFile,
+  changelogTitle,
 });

lib/verify.js

@@ -4,13 +4,17 @@ const getError = require('./get-error');
 const resolveConfig = require('./resolve-config');
 
 module.exports = pluginConfig => {
-  const {changelogFile} = resolveConfig(pluginConfig);
+  const {changelogFile, changelogTitle} = resolveConfig(pluginConfig);
   const errors = [];
 
   if (!isUndefined(changelogFile) && !(isString(changelogFile) && changelogFile.trim())) {
     errors.push(getError('EINVALIDCHANGELOGFILE', {changelogFile}));
   }
 
+  if (!isUndefined(changelogTitle) && !(isString(changelogTitle) && changelogTitle.trim())) {
+    errors.push(getError('EINVALIDCHANGELOGTITLE', {changelogTitle}));
+  }
+
   if (errors.length > 0) {
     throw new AggregateError(errors);
   }

test/prepare.test.js

@@ -53,3 +53,33 @@ test.serial('Prepend the CHANGELOG.md if there is an existing one', async t => {
   t.is((await readFile('CHANGELOG.md')).toString(), `${notes}\n\nInitial CHANGELOG\n`);
   t.deepEqual(t.context.log.args[0], ['Update %s', 'CHANGELOG.md']);
 });
+
+test.serial('Prepend title in the CHANGELOG.md if there is none', async t => {
+  const notes = 'Test release note';
+  await outputFile('CHANGELOG.md', 'Initial CHANGELOG');
+
+  const changelogTitle = '# My Changelog Title';
+  await prepare({changelogTitle}, notes, t.context.logger);
+
+  t.is((await readFile('CHANGELOG.md')).toString(), `${changelogTitle}\n\n${notes}\n\nInitial CHANGELOG\n`);
+});
+
+test.serial('Keep the title at the top of the CHANGELOG.md', async t => {
+  const notes = 'Test release note';
+  const changelogTitle = '# My Changelog Title';
+  await outputFile('CHANGELOG.md', `${changelogTitle}\n\nInitial CHANGELOG`);
+
+  await prepare({changelogTitle}, notes, t.context.logger);
+
+  t.is((await readFile('CHANGELOG.md')).toString(), `${changelogTitle}\n\n${notes}\n\nInitial CHANGELOG\n`);
+});
+
+test.serial('Create new changelog with title if specified', async t => {
+  const notes = 'Test release note';
+  const changelogTitle = '# My Changelog Title';
+  const changelogFile = 'HISTORY.md';
+
+  await prepare({changelogTitle, changelogFile}, notes, t.context.logger);
+
+  t.is((await readFile(changelogFile)).toString(), `${changelogTitle}\n\n${notes}\n`);
+});

test/verify.test.js

@@ -1,12 +1,13 @@
 import test from 'ava';
 import verify from '../lib/verify';
 
-test.serial('Verify String "changelogFile"', t => {
+test.serial('Verify String "changelogFile" and "chagngelogTitle"', t => {
   const changelogFile = 'docs/changelog.txt';
-  t.notThrows(() => verify({changelogFile}));
+  const changelogTitle = '# My title here';
+  t.notThrows(() => verify({changelogFile, changelogTitle}));
 });
 
-test.serial('Verify undefined "changelogFile"', t => {
+test.serial('Verify undefined "changelogFile" and "chagngelogTitle"', t => {
   t.notThrows(() => verify({}));
 });
 
@@ -33,3 +34,26 @@ test('Throw SemanticReleaseError if "changelogFile" option is a whitespace Strin
   t.is(error.name, 'SemanticReleaseError');
   t.is(error.code, 'EINVALIDCHANGELOGFILE');
 });
+
+test('Throw SemanticReleaseError if "changelogTitle" option is not a String', t => {
+  const changelogTitle = 42;
+  const [error] = t.throws(() => verify({changelogTitle}));
+
+  t.is(error.name, 'SemanticReleaseError');
+  t.is(error.code, 'EINVALIDCHANGELOGTITLE');
+});
+
+test('Throw SemanticReleaseError if "changelogTitle" option is an empty String', t => {
+  const [error] = t.throws(() => verify({changelogTitle: ''}));
+
+  t.is(error.name, 'SemanticReleaseError');
+  t.is(error.code, 'EINVALIDCHANGELOGTITLE');
+});
+
+test('Throw SemanticReleaseError if "changelogTitle" option is a whitespace String', t => {
+  const changelogTitle = '  \n \r ';
+  const [error] = t.throws(() => verify({changelogTitle}));
+
+  t.is(error.name, 'SemanticReleaseError');
+  t.is(error.code, 'EINVALIDCHANGELOGTITLE');
+});