Merge pull request #24 from stronk7/release_docs_clarifications

Complete the release docs with some important details

Author: kabalin

.travis.yml

@@ -73,6 +73,7 @@ jobs:
     - php: 7.0
       env: MOODLE_BRANCH=MOODLE_35_STABLE
     - stage: Deploy
+      if: tag IS present
       before_install: skip
       install: skip
       script: skip
@@ -83,7 +84,7 @@ jobs:
         provider: releases
         api_key: $GITHUB_TOKEN
         file: build/moodle-plugin-ci.phar
-        cleanup: false
+        skip_cleanup: true
         on:
           repo: moodlehq/moodle-plugin-ci
           tags: true

README.md

@@ -7,7 +7,10 @@ The goal of this project is to facilitate the running of tests and code analysis
 [Travis CI](https://travis-ci.org).  All of these tests and tools are run everytime a change is pushed to a GitHub
 branch or pull request.
 
-All documentation, guides, change log, etc can be found here: https://moodlehq.github.io/moodle-plugin-ci/
+* [Getting started](https://moodlehq.github.io/moodle-plugin-ci/)
+* [Help topics](https://moodlehq.github.io/moodle-plugin-ci/Help.html)
+* [Changelog](https://moodlehq.github.io/moodle-plugin-ci/CHANGELOG.html)
+* [Upgrade 3.0](https://moodlehq.github.io/moodle-plugin-ci/UPGRADE-3.0.html)
 
 History, acknowledgement and appreciation
 =========================================

docs/CHANGELOG.md

@@ -36,6 +36,7 @@ No unreleased changes.
 
 ### Added
 - New help document: [CLI commands and options](CLI.md)
+- Upgrade guide: [Upgrading from 2.X to 3.0](UPGRADE-3.0.md)
 
 ### Removed
 - Support for PHP 5.x (7.0.0 is now required).

docs/ReleaseNewVersion.md

@@ -13,9 +13,34 @@ Prior to tagging a release, ensure the following have been updated:
 * If this is a new major version, then the `.travis.dist.yml` and `doc/TravisFileExplained.md` need to be updated
   to use the new major version.  Any other version will automatically be used.
 
-As of writing this, releases are made from the `master` branch.  To tag a release, use a commands like the following:
+When all the changes above have been performed, push them straight upstream to `master` (or create a standard PR
+to get them reviewed and incorporated upstream, but **avoid merge commit**, use "Rebase and merge" instead).
+
+Once all code and commits are in place and verified, you need to tag a release.
+
+There are two options: you can tag `master` branch `HEAD` and push using commands:
 
 ```bash
-$ git tag -a 1.0.0 -m "Release version 1.0.0"
-$ git push origin 1.0.0
-```
+$ git tag -a 3.1.0 -m "Release version 3.1.0"
+$ git push origin 3.1.0
+```
+Alternatively, you can use GitHub interface to tag: click "Draft a new release" and specify
+tag using the interface (you can leave title field empty, tag will be used as
+title in this case) and click "Publish release".
+
+In either option, when the tag is pushed or created via interface, travis will
+trigger a tag build that contains Deploy stage. At this stage it should
+automatically create the `moodle-plugin-ci.phar` release artifact and add it
+to the latest release "assets" on GitHub. Verify it has worked correctly by
+navigating at
+[Releases](https://github.com/moodlehq/moodle-plugin-ci/releases).
+
+If there is any problem with that automatic deployment, the artifact will need to be created manually. First build PHAR file manually:
+
+```bash
+$ make build/moodle-plugin-ci.phar
+```
+
+Once the above command suceeded, navigate to latest release in [GitHub
+interface](https://github.com/moodlehq/moodle-plugin-ci/releases), click
+"Edit" and attach generated PHAR file to release (you will find it at `./build` subdir).