Merge branch 'release-1.1.0'

.gitignore

@@ -58,3 +58,5 @@ typings/
 .env
 
 .nyc_output
+
+tests/integration/work

HISTORY.md

@@ -1,4 +1,4 @@
-# TAO Extension Realse Tool history
+# TAO Extension Release Tool history
 
 ## [Version 0.1.0](https://github.com/oat-sa/tao-extension-release/releases/tag/0.1.0)
 
@@ -9,31 +9,38 @@
 
 ## [Version 0.2.0](https://github.com/oat-sa/tao-extension-release/releases/tag/0.2.0)
 
- - windows support
+ - Windows support
  - update notification
 
-
 ## [Version 0.2.1](https://github.com/oat-sa/tao-extension-release/releases/tag/0.2.1)
 
- - fix windows home path
+ - fix Windows home path
  - library update
 
 ## [Version 0.3.0](https://github.com/oat-sa/tao-extension-release/releases/tag/0.3.1)
 
  - Add unit and integration tests
- - Add Eslint
+ - Add ESLint
  - Translations are false by default
  - `wwwUser` can be defined in the config file
 
- ## [Version 0.4.0](https://github.com/oat-sa/tao-extension-release/releases/tag/0.4.0)
+## [Version 0.4.0](https://github.com/oat-sa/tao-extension-release/releases/tag/0.4.0)
 
  - Refactor release functionality into separate module
  - Partially migrate application to use github v4 api
  - Extract release notes from github pull requests
- - Introduce `base-branch`, `branch-prefix`, `origin`, `release-branch`, `www-user`  command line arguments
+ - Introduce `base-branch`, `branch-prefix`, `origin`, `release-branch`, `www-user` command line arguments
  - Cover changes with unit tests
 
+## [Version 0.4.1](https://github.com/oat-sa/tao-extension-release/releases/tag/0.4.1)
+
+ - Enforce npm install
 
- ## [Version 0.4.1](https://github.com/oat-sa/tao-extension-release/releases/tag/0.4.1)
+## [Version 1.1.0]
 
- - Enforce npm install 
+ - Introduce npm commander for CLI params
+ - Add `prepareRelease` & `createRelease` commands
+ - Keep old process as `oldWayRelease`
+ - Add `npmRelease` command
+ - npm install the extension/views before release
+ - Make release note extraction more robust

README.md

@@ -1,6 +1,6 @@
 # tao-extension-release
 
-This tool automate TAO extension release
+This tool automates TAO extension release
 
 ## Installation
 
@@ -12,23 +12,81 @@ npm i -g @oat-sa/tao-extension-release
 
 ## Release an extension
 
-Run :
+Extension release now happens in 2 stages: the preparation and the release.
+
+### prepareRelease
+
+The first stage prepares the releasing branch, compiles assets and translations, and pushes the branch to the remote repo, ready to be tested, deployed or released.
+
+```sh
+taoRelease prepareRelease
+```
+
+### createRelease
+
+The second stage retrieves a prepared releasing branch from the remote repo, brings it up to date, and executes the release.
+
+```sh
+taoRelease createRelease
+```
+
+You will be prompted to follow the instructions.
+
+### oldWayRelease (deprecated)
+
+The `taoRelease oldWayRelease` command launches the sequence used by the old version (<= 0.4.1) of this tool. Functionally it is equivalent to running `prepareRelease` followed immediately by `createRelease`, but there is no opportunity to do any deployment or testing at the mid-point of the process.
+
+## Release an npm package
+
+There is also a command to perform the Github release, and npm publishing, of frontend packages. Unlike the above commands, this one *must* be run in the root directory of an npm package repo.
 
 ```sh
-taoRelease
+cd path/to/my/package/repo
+taoRelease npmRelease
 ```
 
-and follow the instructions
+The sequence of steps to be followed is very similar. At then end, you will be prompted to trigger the execution of `npm publish`. The Github release is already finished at this stage. If the publish step fails, you can try again manually, or ask someone with the necessary privileges to perform the publishing.
 
 ## Commandline arguments
 
-Commandline arguments:
+Commandline arguments to give you more control over the parameters of the release:
+
+### Common options
+
+| option | description | default |
+|---|---|---|
+|`--base-branch <branch>`|branch to release from|`develop`|
+|`--branch-prefix <prefix>`|releasing branch prefix|`release`|
+|`--origin <remote>`|git repository remote name|`origin`|
+|`--release-branch <branch>`|branch to release to|`master`|
+
+### prepareRelease extra options
+
+| option | description | default |
+|---|---|---|
+|`--path-to-tao <path>`|relative or absolute filesystem path|(none - prompted)|
+|`--extension-to-release <extension>`|extension name (e.g. taoFoobar)|(none - prompted)|
+|`--update-translations`|flag to indicate translation files should be updated|(none - prompted)|
+|`--www-user <user>`|the system user used to launch PHP commands|`www-data`|
+
+### createRelease extra options
+
+| option | description | default |
+|---|---|---|
+|`--path-to-tao <path>`|relative or absolute filesystem path|(none - prompted)|
+|`--extension-to-release <extension>`|extension name (e.g. taoFoobar)|(none - prompted)|
+|`--version-to-release <version>`|version of remote branch to retrieve (e.g. 1.2.3)|(none - prompted)|
+|`--update-translations`|flag to indicate translation files should be updated|(none - prompted)|
+|`--www-user <user>`|the system user used to launch PHP commands|`www-data`|
+|`--release-comment <comment>`|comment to attach to the release|(none - prompted)|
 
- - `--base-branch` - branch to release from. 'develop' by default
- - `--branch-prefix` - releasing branch prefix. 'release' by default
- - `--origin` - git repository origin. 'origin' by default
- - `--release-branch` - branch to release to. 'master' by default
- - `--www-user` - www user. 'www-data' by default
+For absolute control, specify both `--branch-prefix` and `--version-to-release`. That way, the program is guaranteed to retrieve the remote branch named e.g. `release-1.2.3`, which could be helpful if there are multiple remote branches with similar names.
+
+### npmRelease extra options
+
+| option | description | default |
+|---|---|---|
+|`--release-comment <comment>`|comment to attach to the release|(none - prompted)|
 
 ## Development
 
@@ -56,7 +114,6 @@ Useful commands :
  - `npm run test:dev` runs the test suite in watch mode
  - `npm run lint` verifies the sources complies with the code style guide
 
-
 ## Configuration
 
 A file named `.tao-extension-release` is created in the user directory.
@@ -66,7 +123,6 @@ The following values can be defined in this file :
  - `taoRoot` : the path to the root of TAO
  - `wwwUser` : the system user used to launch PHP commands (`www-data`)
 
-
 ## System Prerequisite
 <a name="prerequisite"></a>
 
@@ -77,10 +133,12 @@ You need a recent version of [node.js](https://nodejs.org) for your platform :
  - [Windows installer](https://nodejs.org/dist/v8.7.0/node-v8.7.0-x86.msi)
  - [OSX installer](https://nodejs.org/dist/v8.7.0/node-v8.7.0.pkg)
  - Linux package
+
 ```sh
 curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
 sudo apt-get install -y nodejs
 ```
+
  - or using [nvm](https://github.com/creationix/nvm#installation) for multiple versions.
 
 #### git
@@ -95,7 +153,6 @@ You also need the `php` command available in your `PATH`.
 
 You also need the `sudo` command available in your `PATH`.
 
-
 ## Known Issues
 
 ### `Task foosass not found`
@@ -113,5 +170,5 @@ See the [history](HISTORY.md)
 
 ## License
 
-Copyright (c) 2017 Open Assessment Technologies SA;
+Copyright (c) 2017-2019 Open Assessment Technologies SA;
 [GNU General Public License v2.0](https://github.com/oat-sa/tao-extension-release/blob/master/LICENSE)

docs/taoRelease createRelease of v1.2.4 following v1.2.3.txt

@@ -0,0 +1,52 @@
+title taoRelease createRelease of v1.2.4 following v1.2.3
+
+participantspacing 4
+participantgroup #azure **Local repo**
+materialdesignicons f2a2 "master" as LM
+materialdesignicons f2a2 "develop" as LD
+materialdesignicons f2a2 "release-1.2.4" as LR
+end
+participantgroup #ivory **Remote repo**
+materialdesignicons f2a4 "release-1.2.4" as RR
+materialdesignicons f2a4 "master" as RM
+materialdesignicons f2a4 "develop" as RD
+end
+
+==following on from: prepareRelease of v1.2.4==#lightgreen
+parallel
+note over RM: v1.2.3
+note over RR#yellow: v1.2.4
+parallel off
+
+RR->*LR: checkout & pull  
+activate LR
+RM->LM: fetch & pull master
+LM->LR: merge master
+rbox over LR: compile JS+CSS
+LR->LR: commit
+LR->RR: push
+activate RR
+
+rbox over RR: create PR to master
+RR-->>RM: PR
+
+activate RM
+rbox over RM: extract release notes
+note over RR#lightpink: **human checks**
+RR->RM: merge
+rbox over RM: tag v1.2.4
+rbox over RM: release v1.2.4
+note over RM#lawngreen: **v1.2.4 is released!**
+
+RM->LM: checkout & pull master
+deactivate RM
+LM->LD: <align:center>merge\n(fast-forward)</align>
+LD->RD: push
+note over RD: <align:center>v1.2.4\nequal with master</align>
+
+rbox over RR: delete branch
+deactivate RR
+destroyafter RR
+rbox over LR: delete branch
+deactivate LR
+destroyafter LR

docs/taoRelease oldWayRelease of v1.2.4 following v1.2.3.txt

@@ -0,0 +1,58 @@
+title taoRelease oldWayRelease of v1.2.4 following v1.2.3
+
+participantspacing 4
+participantgroup #azure **Local repo**
+materialdesignicons f2a2 "master" as LM
+materialdesignicons f2a2 "develop" as LD
+materialdesignicons f2a2 "release-1.2.4" as LR
+end
+participantgroup #ivory **Remote repo**
+materialdesignicons f2a4 "release-1.2.4" as RR
+materialdesignicons f2a4 "master" as RM
+materialdesignicons f2a4 "develop" as RD
+end
+
+
+parallel
+note over RM: v1.2.3
+note over RD: v1.2.4
+parallel off
+
+RM->LM: checkout & pull master
+RD->LD: checkout & pull develop
+LM<<-->>LD: compare
+
+LD->*LR: <align:center>checkout\nnew branch</align>
+activate LR
+rbox over LR: compile JS+CSS
+LR->LR: commit
+LR->*RR: push
+activate RR
+rbox over LR: update translations?
+LR->LR: commit
+LR->RR: push
+
+note over RR#yellow: branch ready!
+rbox over RR: create PR to master
+RR-->>RM: PR
+
+activate RM
+rbox over RM: extract release notes
+note over RR#lightpink: **human checks**
+RR->RM: merge
+rbox over RM: tag v1.2.4
+rbox over RM: release v1.2.4
+note over RM#lawngreen: **v1.2.4 is released!**
+
+RM->LM: checkout & pull master
+deactivate RM
+LM->LD: <align:center>merge\n(fast-forward)</align>
+LD->RD: push
+note over RD: <align:center>v1.2.4\nequal with master</align>
+
+rbox over RR: delete branch
+deactivate RR
+destroyafter RR
+rbox over LR: delete branch
+deactivate LR
+destroyafter LR

docs/taoRelease prepareRelease of v1.2.4 following v1.2.3.txt

@@ -0,0 +1,38 @@
+title taoRelease prepareRelease of v1.2.4 following v1.2.3
+
+participantspacing 4
+participantgroup #azure **Local repo**
+materialdesignicons f2a2 "master" as LM
+materialdesignicons f2a2 "develop" as LD
+materialdesignicons f2a2 "release-1.2.4" as LR
+end
+participantgroup #ivory **Remote repo**
+materialdesignicons f2a4 "release-1.2.4" as RR
+materialdesignicons f2a4 "master" as RM
+materialdesignicons f2a4 "develop" as RD
+end
+
+
+parallel
+note over RM: v1.2.3
+note over RD: v1.2.4
+parallel off
+
+RM->LM: checkout & pull master
+RD->LD: checkout & pull develop
+LM<<-->>LD: compare
+
+LD->*LR: <align:center>checkout\nnew branch</align>
+activate LR
+rbox over LR: compile JS+CSS
+LR->LR: commit
+LR->*RR: push
+activate RR
+rbox over LR: update translations?
+LR->LR: commit
+LR->RR: push
+
+note over RR#yellow: branch ready!
+deactivate RR
+deactivate LR
+==ready for next step: createRelease of v1.2.4==#lightgreen