Merge pull request #4 from UFHealth/feature/docs-and-generators

Feature/docs and generators

CHANGELOG.md

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+### 0.3.0 - 02/06/2020
+
+**New**
+- Added `--generate` option for generating YAML files from the provided `template.yml`.
+- Added docs for YAML formatting and categories.
+- Added 'External' category for jargon-free changelog notes.
+
+**Updated**
+- Added a better error message for missing changelog when version bumping.
+- Added date stamps when generating the header for CHANGELOG content.
+
 ### 0.2.1
 
 **Fixed**

README.md

@@ -79,6 +79,28 @@ A few caveats:
 - Regular expression stuff is supported, but if you want to use subgroups like `(a|b|c)`, they must be _non-matching_ (i.e. `(?:a|b|c)`).
 - Currently only one `<version>` placeholder per pattern is supported, so if you need to replace multiple version references in the same line, you'll have to use either regex voodoo or more than one pattern.
 
+### Changelog Category Reference
+
+Available categories:
+
+**new**: notes on new features
+
+**updated**: notes on feature enhancements 
+
+**fixed**: notes on bug fixes
+
+**external**: notes that will provided as a non-technical changelog to end users -- *do not use technical jargon here!*
+
+Format for writing changelog notes:
+```yml
+new:
+  - New thing 1
+  - New thing 2
+
+external:
+  - Thing 1 and Thing 2 are now ready to be used!
+```
+*Note:* You can omit any category, as long as you have one you are good to go!
 
 ## Runit
 

bin/shipit.js

@@ -15,6 +15,7 @@ const {
   getCurrentVersion,
   parseSources,
   updateChangelog,
+  generateLogYml
 } = require('../lib/api')
 
 // ---------------------------------------------------------------------------------------------
@@ -29,12 +30,20 @@ const helpText = `
     version  The next version of your package.
 
   Options:
-    --help     Display this help message.
-    --version  Print the current shipit version.
-    --dry-run  See what would happen if you ran this command IRL.
+    --dry-run          See what would happen if you ran this command IRL.
+    --generate=<name>  Generate a YAML file for logging your changes.
+    --help             Display this help message.
+    --version          Print the current shipit version.
 `
 
 const main = async (argv, config) => {
+  const generate = argv.generate || false
+
+  if (generate) {
+    await generateLogYml(generate, config)
+    return
+  }
+
   // Grab version
   const version = argv._[0] || false
   if (!version) {

lib/api.js

@@ -5,6 +5,7 @@ const merge = require('lodash.mergewith')
 const { parse: parseYaml } = require('yaml')
 const path = require('path')
 const replace = require('replace-in-file')
+const chalk = require('chalk')
 
 // ---------------------------------------------------------------------------------------------
 
@@ -44,7 +45,13 @@ const globAsync = (pattern) => new Promise((resolve, reject) => {
  */
 const parseSources = async (sourcePath) => {
   if (!await fs.pathExists(sourcePath)) {
-    throw new Error(`source path doesn't exist`)
+    throw new Error(chalk.redBright('\n\n🚨 A changelog entry is required.')
+      + '\n\n' + chalk.yellow('Use the generator to scaffold a changelog:')
+      + '\n' + 'shipit --generate=yourLogNameHere'
+      + '\n\n' + chalk.yellow('Alternatively, create changelog notes manually:')
+      + '\n' + 'touch ' + sourcePath + '/yourLogNameHere.yml'
+      + '\n'
+    )
   }
 
   const mergeHandler = (dest, src) => {
@@ -62,6 +69,7 @@ const parseSources = async (sourcePath) => {
     new: [],
     updated: [],
     fixed: [],
+    external: [],
   }, ...parsedFiles, mergeHandler)
 }
 
@@ -80,7 +88,12 @@ const generateMarkdown = (changes, version) => {
 
   const generateList = (items) => (items.map((item) => `- ${item}`)).join('\n')
 
-  let content = `### ${version}\n`
+  let today = new Date()
+  const timeStamp = String(today.getMonth() + 1).padStart(2, '0')
+    + '/' + String(today.getDate()).padStart(2, '0')
+    + '/' + today.getFullYear()
+
+  let content = `### ${version} - ${timeStamp}\n`
   if (changes.new.length) {
     content += `\n**New**\n${generateList(changes.new)}\n`
   }
@@ -90,6 +103,9 @@ const generateMarkdown = (changes, version) => {
   if (changes.fixed.length) {
     content += `\n**Fixed**\n${generateList(changes.fixed)}\n`
   }
+  if (changes.external.length) {
+    content += `\n**Notes for humans**\n${generateList(changes.external)}\n`
+  }
 
   return content
 }
@@ -263,6 +279,13 @@ const bumpVersion = async (path, replacements, oldVersion, newVersion, dryRun =
   return result.reduce((total, entry) => entry.numReplacements + total, 0)
 }
 
+const generateLogYml = async (fileName, config) => {
+  const purifiedName = fileName.replace(/\s+/g, '-').toLowerCase() + '.yml'
+  console.log(chalk.green('⚙️  Generating...'))
+  await fs.copy(path.resolve('./lib/template.yml'), config.source + '/' + purifiedName)
+  console.log(chalk.green('✅ ' + config.source + '/' + purifiedName))
+}
+
 module.exports = {
   parseSources,
   generateMarkdown,
@@ -271,4 +294,5 @@ module.exports = {
   getCurrentVersion,
   bumpPackageJson,
   bumpVersion,
+  generateLogYml
 }

lib/template.yml

@@ -0,0 +1,11 @@
+new:
+  - Notes
+
+updated:
+  - Notes
+
+fixed:
+  - Notes
+
+external:
+  - Notes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ufhealth/shipit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Release stuff real easy",
   "license": "MIT",
   "author": "UFHealth Web Services <[email protected]>",