alextremp · alextremp · Jan 2, 2020 · Jan 2, 2020 · Jan 2, 2020 · Jan 2, 2020
diff --git a/.travis.yml b/.travis.yml
@@ -8,10 +8,4 @@ cache:
 before_install:
   - npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN
 script:
-  - npm run check
-  - |
-    echo TRAVIS_BRANCH=$TRAVIS_BRANCH - TRAVIS_PULL_REQUEST=$TRAVIS_PULL_REQUEST - TRAVIS_TAG=$TRAVIS_TAG
-    if [[ $TRAVIS_TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-beta\.[0-9]+)?$ ]]; then
-      echo DEPLOY VERSION - TRAVIS_BRANCH=$TRAVIS_BRANCH, PR=$PR, BRANCH=$BRANCH
-      TRAVIS_TAG=$TRAVIS_TAG GH_TOKEN=$GH_TOKEN npm run versiona
-    fi
+  - npm run check && TRAVIS_TAG=$TRAVIS_TAG GH_TOKEN=$GH_TOKEN npm run versiona
diff --git a/README.md b/README.md
@@ -1,59 +1,92 @@
-# versiona [![NPM Module](https://img.shields.io/npm/v/versiona.svg)](https://www.npmjs.com/package/versiona)
+<img alt="versiona logo" src="https://repository-images.githubusercontent.com/230541628/a2f2d400-2d09-11ea-8df8-ed5368f5df5c" width="300">
 
+[![NPM Module](https://img.shields.io/npm/v/versiona.svg)](https://www.npmjs.com/package/versiona)
 [![Build Status](https://travis-ci.org/alextremp/versiona.svg?branch=master)](https://travis-ci.org/alextremp/versiona)
 [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/alextremp/versiona.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/alextremp/versiona/context:javascript)
 [![Maintainability](https://api.codeclimate.com/v1/badges/c2ea0ca1472cb7af910f/maintainability)](https://codeclimate.com/github/alextremp/versiona/maintainability)
 
-**Versiona** is a Travis CI helper tool for NPM projects where teams use Github tags to create new Releases, so assuming:
+# versiona 
+**Versiona** is an utility for Github NPM projects using Travis CI to automatize:
+* Publish a NPM package when a Github tag is created with the vX.Y.Z semver format.
+* Update and commit the new package.json version.
 
-* Use Travis CI
-* Use Github release tagging in semver format:
-  * vX.Y.Z tag will publish X.Y.Z version in NPM
-  * vX.Y.Z-beta.A tag will publish X.Y.Z-beta.A beta version in NPM
+For example, with **versiona** activated in your project:
+
+1. When creating new Release Tag in Github, p.ex. **v1.0.2** release:
+
+<img width="512" alt="creating a new release tag" src="https://user-images.githubusercontent.com/20399660/71648589-a46ecd00-2d06-11ea-9ad9-2bd83f6bed4e.png">
+
+2. **versiona** will publish the v1.0.2 release to NPM:
+
+<img width="512" alt="creating a new release tag" src="https://user-images.githubusercontent.com/20399660/71648966-09c4bd00-2d0b-11ea-8705-05c434bb41a9.png">
+
+3. And also, **versiona** will commit the updated package.json back to Github:
+
+<img width="512" alt="creating a new release tag" src="https://user-images.githubusercontent.com/20399660/71648602-d2541180-2d06-11ea-92c8-b011d6b4b9d9.png">
+
+
+Releasing to NPM this way, your collaborators will be aimed to:
+* Control via Github Releases when a new version should be publicly available.
+* Know which Release Tag corresponds to each available version of the package in NPM.
+* Add documentation to the Github Releases.
+* Not publishing from localhost! ;)
+
+## Requirements
+
+**versiona** can be launched from any command line environment, but will require to have these environment variables available:
+* **NPM_TOKEN**
+  * Will be used to publish the package to NPM.
+  * Check [Creating and Viewing Auth Tokens in NPM](https://docs.npmjs.com/creating-and-viewing-authentication-tokens).
+  * **Read and Publish** permission is required to publish packages.
+* **GH_TOKEN**
+  * Will be used to commit a new package.json version to Github.
+  * Check [Creating a Personal Access Token in Github](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
 
-This library will:
-* Update your package version to the Github tag specific version
-* Publish the new version to NPM
-* Commit to Github the updated package.json
-  * Commit to **master** for Release versions (vX.Y.Z)
-  * Commit to **develop/vX** for Beta Release versions (vX.Y.Z-beta.A)
-
-By releasing your NPM packages this way, your collaborators will be aimed to:
-* have full control of when a new version should be publicly available 
-* know which release tag corresponds to each available NPM version of your package
-* doc the releases :)
-* don't publish from localhost! ;)
+When used in Travis CI, just add these tokens in the Settings of your repo **with the secured option to avoid showing the tokens content in the Travis logs** 
 
 ## Usage
 
-Install versiona:
+
+Install **versiona**:
 
 ```
 npm i versiona --save-dev
 ``` 
 
-Create a **versiona.js** script into your project:
+Create a **versiona.js** script into your project's root (can be ignored in .npmignore):
 
 ```
 const versiona = require('versiona')
 
 versiona({
-  repoOrg: 'your_repo_org_or_username',         // required, ex: 'alextremp'
-  repoName: 'your_repo_name',                   // required, ex: 'versiona'
-  pathToPackageJSON: 'path_to_package.json',    // defaults to 'package.json', set the relative path to package json if it's not in the same folder than the script
-  test: false                                   // true if just want to test the config without publishing / committing, defaults to false     
+  repoOrg: 'your_repo_org_or_username',
+  repoName: 'your_repo_name'
+})
+```
+
+**versiona accepted parameters**:
+* repoOrg: Your username or organization
+* repoName: The repository name
+* host: The Github's host (for enterprise usage, if not, it defaults to 'github.com')
+* test: boolean. _true_ means that it's only to test the configuration, so no package will be published, and no commit will be done to github. (it defaults to false).
+
+Example call from [a project using versiona](https://github.com/alextremp/brusc):
+```
+versiona({
+  repoOrg: 'alextremp',
+  repoName: 'brusc'
 })
 ```
 
-Add a new script task into your package.json:
+**Add a new script task into your package.json**:
 
 ```
 "scripts": {
   "versiona": "node versiona.js"
 }
 ```
 
-Call the versiona task from Travis:
+**Call the versiona task from Travis** editing your .travis.yml:
 
 * In this travis sample:
 ```
@@ -67,18 +100,36 @@ cache:
 before_install:
   - npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN
 script:
-  - npm run check
-  - |
-    echo TRAVIS_BRANCH=$TRAVIS_BRANCH - TRAVIS_PULL_REQUEST=$TRAVIS_PULL_REQUEST - TRAVIS_TAG=$TRAVIS_TAG
-    if [[ $TRAVIS_TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-beta\.[0-9]+)?$ ]]; then
-      echo DEPLOY VERSION - TRAVIS_BRANCH=$TRAVIS_BRANCH, PR=$PR, BRANCH=$BRANCH
-      TRAVIS_TAG=$TRAVIS_TAG GH_TOKEN=$GH_TOKEN npm run versiona
-    fi
+  - npm run check && TRAVIS_TAG=$TRAVIS_TAG GH_TOKEN=$GH_TOKEN npm run versiona
 ```
 
-  * NPM_TOKEN is required to publish packages to NPM
-  * GH_TOKEN is required to commit back to Github
-  * This library only uses the tokens, does not store / send / ... them to anywhere
+In this sample:
+```
+before_install:
+  - npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN
+```
+  * The **NPM_TOKEN** will be required in order to enable the NPM publish command.
+
+```
+npm run check
+```
+  * This is a project task that run the **lint** and **test** tasks to validate the build.
+
+```
+TRAVIS_TAG=$TRAVIS_TAG GH_TOKEN=$GH_TOKEN npm run versiona
+```
+  * This runs **versiona**
+  * **TRAVIS_TAG** is required, **versiona** will check if the TRAVIS_TAG is set and matches the _^v[0-9]+\.[0-9]+\.[0-9]+(-beta\.[0-9]+)?$_ regexp (**semver format**, p.ex.: _v2.3.1_ or _v3.0.0-beta.1_)
+  * If that's not the case, it will exit doing nothing
+  * If the **semver format** is matched, it will validate the **GH_TOKEN** to be set (as it will be required to commit back to Github in next steps):
+    * **For vX.Y.Z format releases**:
+      * It will update the package.json to X.Y.Z version and publish the package.
+      * It will commit to Github in **master** branch the updated package.json using a Travis User with the GH_TOKEN.
+    * **For vX.Y.Z-beta.A format releases**:
+      * It will update the package.json to X.Y.Z-beta.A version and publish the package **as a beta version**.
+      * It will commit to Github in **develop/vX** branch the updated package.json using a Travis User with the GH_TOKEN.
+
+ This library only uses the tokens, does not store / send / ... them to anywhere
 
 
 ## Troubleshooting
@@ -101,5 +152,16 @@ script:
 
 ## Maintainers
 
-This library uses itself to publish to NPM.
+This library uses itself to publish to NPM, so:
+
+This project uses Travis CI for
+* PR validation
+* Merge to master validation
+* NPM publications on Release tag creation
+
+To create a new Release, take in mind:
+* The Release Tag must be named *vX.Y.Z* where X.Y.Z are the _semver_ numbers that will correspond to the published package's version.
+* Travis CI will launch [versiona](https://www.npmjs.com/package/versiona) which will:
+  * Update the package.json to the X.Y.Z version set in the Release Tag
+  * Publish the NPM package with the X.Y.Z version
 
diff --git a/src/main/runner.js b/src/main/runner.js
@@ -5,6 +5,7 @@ import {log} from './logger'
 const queue = []
 
 const run = () => {
+  log.info(() => 'Start execution...')
   queue.forEach(command => {
     try {
       command()
@@ -22,9 +23,13 @@ const run = () => {
   log.info(() => 'Finished')
 }
 
-const addFunction = f => queue.push(() => f())
+const addFunction = (name, f) => {
+  log.info(() => ['Added function', {name}])
+  queue.push(() => f())
+}
 
 const addShell = command => {
+  log.info(() => ['Added shell command', {command}])
   queue.push(() => {
     log.info(() => ['command', {command}])
     const result = shell.exec(command)

diff --git a/src/main/versiona.js b/src/main/versiona.js
@@ -19,18 +19,20 @@ const versiona = ({
   }
   const travisTag = process.env.TRAVIS_TAG
   if (!travisTag) {
-    log.error(() => 'TRAVIS_TAG is not in process env')
-    quit()
+    log.info(
+      () => 'TRAVIS_TAG is not present in process.env, stopping versiona'
+    )
+    quit(0)
   }
   if (!REGEX.test(travisTag)) {
-    log.error(() => [
-      'TRAVIS_TAG not accepted',
+    log.info(() => [
+      'TRAVIS_TAG is not a semver format tag, stopping versiona',
       {
         received: travisTag,
-        expected: REGEX
+        semver: REGEX
       }
     ])
-    quit()
+    quit(0)
   }
   const ghToken = process.env.GH_TOKEN
   if (!ghToken) {
@@ -69,10 +71,6 @@ const versiona = ({
     }
   ])
 
-  if (test) {
-    log.info(() => 'Test finished')
-    quit(0)
-  }
   addShell(`git remote rm origin`)
   addShell(`git remote add origin ${repoURL}`)
   addShell(`git checkout -b ${toBranch}`)
@@ -82,6 +80,10 @@ const versiona = ({
   addShell(`npm publish${isBeta ? ' --tag beta' : ''}`)
   addShell(`git push --repo=${repoURL} origin ${toBranch} --quiet`)
 
+  if (test) {
+    log.info(() => 'Test finished')
+    quit(0)
+  }
   run()
 }