use new release management rules

.circleci/config.yml

@@ -1,11 +1,10 @@
 version: 2
 jobs:
-
-  htlengine:
-    parallelism: 4
+  build:
     docker:
-    # specify the version you desire here
     - image: circleci/node:8
+      environment:
+        NPM_CONFIG_PREFIX: "~/.npm-global"
 
     working_directory: ~/repo
 
@@ -15,7 +14,14 @@ jobs:
     # Download and cache dependencies
     - restore_cache:
         keys:
-        - v3-dependencies-{{ checksum "package.json" }}
+        - v3-dependencies-{{ checksum "package-lock.json" }}
+    - run:
+        name: Set up global NPM
+        command: mkdir ~/.npm-global
+
+    - run:
+        name: install npm 6.4.0
+        command: sudo npm -g install npm@6.4.0
 
     - run:
         name: Install Dependencies
@@ -24,24 +30,40 @@ jobs:
     - save_cache:
         paths:
         - node_modules
-        key: v3-dependencies-{{ checksum "package.json" }}
+        key: v3-dependencies-{{ checksum "package-lock.json" }}
+
+    - run:
+        name: Lint
+        command: npm run lint
 
     # run tests!
-    - run: mkdir -p junit
+    - run: mkdir junit
+    - run:
+        name: prepare test git user
+        command: git config --global user.email "you@example.com" && git config --global user.name "CircleCi Build"
     - run:
         name: Running Tests
-        # run tests in parallel: https://circleci.com/docs/2.0/parallelism-faster-jobs/
-        command: circleci tests glob test/*.js | circleci tests split --split-by=timings | xargs npx mocha --reporter mocha-junit-reporter
+        command: npx mocha --reporter mocha-junit-reporter
+        environment:
+          MOCHA_FILE: junit/test-results.xml
+        when: always
+
+
+    # get code coverage
+    - run:
+        name: Getting Code Coverage
+        command: npx istanbul cover ./node_modules/mocha/bin/_mocha -- -R spec && npx codecov
         environment:
           MOCHA_FILE: junit/test-results.xml
         when: always
 
     - store_test_results:
         path: junit
+
     - store_artifacts:
         path: junit
 
-  publish-snapshot:
+  publish-pre-release:
     docker:
     # specify the version you desire here
     - image: circleci/node:8
@@ -51,43 +73,58 @@ jobs:
     steps:
     - checkout
 
-    # Download and cache dependencies
     - restore_cache:
         keys:
-        - v3-dependencies-{{ checksum "package.json" }}
+        - v3-dependencies-{{ checksum "package-lock.json" }}
+
+    - add_ssh_keys:
+        fingerprints:
+        - "40:91:c6:3a:ab:30:f0:68:e2:fd:1d:07:8c:61:d2:9a"
 
     - run:
-        name: Install Dependencies
-        command: npm install && npm install mocha-junit-reporter npm-snapshot
+        name: prepare test git user
+        command: git config --global user.email "circleci@example.com" && git config --global user.name "CircleCi Build"
 
-    - save_cache:
-        paths:
-        - node_modules
-        key: v3-dependencies-{{ checksum "package.json" }}
+    - run:
+        name: install npm 6.4.0
+        command: sudo npm -g install npm@6.4.0
 
-    - run: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
+    - run:
+        name: install
+        command: npm install
 
     - run:
-        command: BUILD_TAG=$(./node_modules/.bin/npm-snapshot $CIRCLE_BUILD_NUM) echo 'export BUILD_TAG=$BUILD_TAG' >> $BASH_ENV
+        name: revert changes to package-lock.json
+        command: git checkout -- package-lock.json
 
     - run:
-        name: Publish Snapshot
-        command: npm publish --access public --tag next
+        name: configure npm registry
+        command: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
 
-    - store_test_results:
-        path: junit
-    - store_artifacts:
-        path: junit
+    - run:
+        name: version pre-release
+        command: npm version prerelease --preid=pre -m "Release %s [ci skip]"
+
+    # unfortunately we cannot create a release commit with no tag with `npm version`, so we need to delete it here again
+    - run:
+        name: delete pre-release tag
+        command: npm run delete-git-tag
+
+    - run:
+        name: publish pre-release
+        command: npm publish --tag next --access public
 
 workflows:
   version: 2
   build:
     jobs:
-    - publish-snapshot:
+    # run build on any branch
+    - build
+
+    # publish pre-releases on master
+    - publish-pre-release:
         requires:
-        - htlengine
+        - build
         filters:
           branches:
-            only:
-            - master
-    - htlengine
+            only: master

CONTRIBUTING.md

@@ -66,15 +66,56 @@ One of the maintainers will look at the pull request within one week. If you hav
 
 Feedback on the pull request will be given in writing, in GitHub.
 
-# Release Management
+# Releasing
+
+## NPM Packages
 
 The project's committers will release to the [Adobe organization on npmjs.org](https://www.npmjs.com/org/adobe).
 Please contact the [Adobe Open Source Advisory Board](https://git.corp.adobe.com/OpenSourceAdvisoryBoard/discuss/issues) to get access to the npmjs organization.
-Then, you can release using:
 
+Package version follow [semantic versioning](https://github.com/npm/node-semver). But since most of
+our packages still are on 0.x, it is rather good practice to use minor / patch versions accordingly.
+
+Our CI automatically creates a new [pre-release](https://semver.org/#spec-item-9) versions for every 
+merged pull request.  The _pre-release_ versions have the form `x.y.z-pre.c` (where `c` is a counter). 
+The subsequent release version `(x.y.z)` will take [precedence](https://semver.org/#spec-item-11)
+over the _pre-release_ version. 
+
+the _pre-release_ versions are attributed with the [dist-tag](https://docs.npmjs.com/cli/dist-tag) `@next`.
+
+### How to cut a release
+
+Based on the changes that follow up a release, we used [semantic versioning](https://github.com/npm/node-semver)
+to define the next release type: `major`, `minor` or `patch`: 
+
+> **Note:** The packages have a `postversion` script that will push the updated package.json along
+> with the git-tag. so no need to do this manually
+  
+Creating a _patch_ release:
+
+```bash
+$ npm version patch
+$ npm publish --tag latest --access public
+```
+
+Creating a _minor_ release:
+
 ```bash
-$ npm login
-$ npm publish --access public
+$ npm version minor
+$ npm publish --tag latest --access public
 ```
 
-Do not forget to add a `git tag` corresponding to the released version number
+Creating a _major_ release:
+
+```bash
+$ npm version major
+$ npm publish --tag latest --access public
+```
+
+### Adding release notes
+
+It is good practice to write some release notes on git for the respective release.
+For example: https://github.com/adobe/helix-cli/releases/tag/v0.3.1
+
+In the future, the release notes can be generated automatically from the information from git issues
+and commits.

package.json

@@ -16,7 +16,10 @@
   "scripts": {
     "test": "mocha",
     "build": "antlr4 -Dlanguage=JavaScript -Xexact-output-dir -o src/parser/generated src/parser/grammar/SightlyLexer.g4 src/parser/grammar/SightlyParser.g4 src/parser/grammar/SightlyParser.g4",
-    "lint": "./node_modules/.bin/eslint src/ test/"
+    "lint": "./node_modules/.bin/eslint src/ test/",
+    "preversion": "npm test",
+    "postversion": "git push origin master --follow-tags",
+    "delete-git-tag": "git tag -d v$npm_package_version && git push origin :v$npm_package_version"
   },
   "devDependencies": {
     "eslint": "^4.19.1",
@@ -25,7 +28,6 @@
     "eslint-plugin-jsx-a11y": "^6.0.3",
     "eslint-plugin-react": "^7.9.1",
     "mocha": "^5.2.0",
-    "mocha-junit-reporter": "^1.17.0",
-    "npm-snapshot": "^1.0.3"
+    "mocha-junit-reporter": "^1.17.0"
   }
 }