Documentation directory structure was reworked.

HTML generated doc and md doc can coexist now in `docs` directory.
All scripts related to release are now in ./travis/release directory
The archives generated for releases on github exclude non-client code (CI build configuration and unit tests)
Changed the way releases are handled.
Documented steps to create new release.

.gitattributes

@@ -1,9 +1,10 @@
-
-.gitattributes export-ignore
-.gitignore     export-ignore
-.gitmodules    export-ignore
-.travis.yml    export-ignore
-
-.travis export-ignore
-
-^docs/* linguist-documentation
+.travis                  export-ignore
+.gitattributes           export-ignore
+.gitignore               export-ignore
+.gitmodules              export-ignore
+.travis.yml              export-ignore
+mkdocs.yml               export-ignore
+tests                    export-ignore
+development              export-ignore
+sonar-project.properties export-ignore
+^docs/*                  linguist-documentation

.gitignore

@@ -4,8 +4,8 @@
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
 # User-specific stuff:
 .idea/
-site/
+.sonar/
 pages/
-release/
+release/*
 *.gz
 *.zip

.travis.yml

@@ -49,7 +49,9 @@ env:
 
     #Environment for building a release
     # File containing new version number
-    - CURRENT_BRANCH=${TRAVIS_BRANCH}
+    - CURRENT_BRANCH="${TRAVIS_BRANCH}"
+    - IS_RELEASE_BRANCH="`if [[ $CURRENT_BRANCH =~ ^release/v[0-9]+\.[0-9]+\.[0-9]+.*$ ]]; then echo true; fi`"
+    - UTPLSQL_PROJECT_ROOT=${TRAVIS_BUILD_DIR}
     - UTPLSQL_REPO="utPLSQL/utPLSQL"
     - UTPLSQL_BUILD_NO="${TRAVIS_BUILD_NUMBER:-0}"
     - UTPLSQL_VERSION_PLACEHOLDER='utPLSQL - Version'
@@ -62,14 +64,13 @@ cache:
     - $HOME/.cache
 
 before_install:
-  - bash .travis/update_project_version.sh
 # On trusty, download the zip file into a cachable directory
   - test "$DIST" = precise || export ORACLE_ZIP_DIR=$HOME/.cache
 # If the zip file already exists, do not download it again
   - test -f "$ORACLE_ZIP_DIR"/$(basename $ORACLE_FILE) || bash .travis/oracle/download.sh
 
 install:
-  - sudo pip install -r .travis/python_req.txt
+  - sudo pip install mkdocs
   - bash .travis/oracle/install.sh
   - bash .travis/create_utplsql_owner.sh
   - bash .travis/create_utplsql_user.sh
@@ -80,24 +81,23 @@ script:
   - bash .travis/run_examples_as_owner.sh
   - bash .travis/run_examples_as_user.sh
   - bash .travis/run_test_as_owner.sh
-#  - bash .travis/push_docs_to_gh_pages.sh
   - sonar-scanner
   - bash .travis/coveralls_uploader.sh
 
 before_deploy:
-  - bash .travis/build_docs.sh
-  - bash .travis/build_release_archive.sh
+  - git clean -d -f -q
+  - bash .travis/release/update_project_version.sh
+  - bash .travis/release/build_docs.sh
+#  - bash .travis/push_docs_to_gh_pages.sh
 
 deploy:
-  provider: releases
-  api_key: $github_api_token
-  file:
-     - release/utPLSQL${UTPLSQL_VERSION}.zip
-     - release/utPLSQL${UTPLSQL_VERSION}.tar.gz
+  provider: script
+  script: bash .travis/release/make_release.sh
   skip_cleanup: true
   on:
-     repo: ${UTPLSQL_REPO}
-     tags: true
+    repo: ${UTPLSQL_REPO}
+    condition: ${IS_RELEASE_BRANCH} == true
+    all_branches: true
 
 notifications:
   slack: utplsql:oiMuXO95TvKeAUENuDt4cPrB

.travis/push_docs_to_gh_pages.sh

@@ -1,45 +1,45 @@
 #!/bin/bash
- 
+
 # Many aspsects of this came from https://gist.github.com/domenic/ec8b0fc8ab45f39403dd
 # Significant alterations
-# - Avoid pulling all history for cloned repo 
-# - Support for multiple copies of documenation, 
+# - Avoid pulling all history for cloned repo
+# - Support for multiple copies of documenation,
 #   - only clearing out latest
 #   - doc-history.md logging doc history
 # - Wrapped calls with actual encrypt keys with > /dev/null 2> /dev/null4
 
-# How to run: 
+# How to run:
 #  - From repository root .travis/push_docs_to_gh_pages.sh
 
 # Required files / directories (relative from repo root)
 # - Folder : "site" with that contains latest docs
-# - File   : ".travis/deploy_key.enc" SSH deployment key encrypted by Travis command line tool 
+# - File   : ".travis/deploy_key.enc" SSH deployment key encrypted by Travis command line tool
 
 # Required ENV Variables
 #  ENCRYPTION_LABEL  - Manually Set in travis web settings.  Value can be displayed in LOG
 #  encrypted_${ENCRYPTION_LABEL}_key - Set in web settings using travis cmdline encryption
-#  encrypted_${ENCRYPTION_LABEL}_iv  - Set in web settings using travis cmdline encryption 
+#  encrypted_${ENCRYPTION_LABEL}_iv  - Set in web settings using travis cmdline encryption
 #  PAGES_TARGET_BRANCH="gh-pages"   - Set in .travis.yml, branch were pages will be deployed
 #  PAGES_VERSION_BASE="version3" -Set in .travis.yml, directory for pages deployment
 #  TRAVIS_* variables are set by travis directly and only need to be if testing externally
 
 # Pull requests are special...
 # They won't have acceess to the encrypted variables.
 # This prevent access to the Encrypted SSH Key
-# Regardless we don't want a pull request automatically updating the repository 
-if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then  
+# Regardless we don't want a pull request automatically updating the repository
+if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
 
   # ENV Variable checks are to help with configuration troubleshooting
   # they silently exit with unique message.  Anyone one of them not set
-  # can be used to turn off this functionality.  
-  # For example a feature branch in the master repository that we don't want docs produced for yet.  
+  # can be used to turn off this functionality.
+  # For example a feature branch in the master repository that we don't want docs produced for yet.
   [[ -n "$PAGES_VERSION_BASE" ]] || { echo "PAGES_VERSION_BASE Missing";  exit 0; }
   [[ -n "$PAGES_TARGET_BRANCH" ]] || { echo "PAGES_TARGET_BRANCH Missing";  exit 0; }
   [[ -n "$ENCRYPTION_LABEL" ]] || { echo "ENCRYPTION_LABEL Missing";  exit 0; }
- 
+
   # Fail because required script to generate documenation must have not been run, or was changed.
   [[ -d ./site ]] || { echo "site directory not found";  exit 1; }
-  
+
   # Save some useful information
   REPO=`git config remote.origin.url`
   SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:}
@@ -50,32 +50,32 @@ if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
   cd pages
   git clone --depth 1 $REPO .
   PAGES_BRANCH_EXISTS=$(git ls-remote --heads $REPO $PAGES_TARGET_BRANCH)
- 
+
   if [ -n "$PAGES_BRANCH_EXISTS" ] ; then
     echo "Pages Branch Found"
     echo "-$PAGES_BRANCH_EXISTS-"
     git remote set-branches origin  $PAGES_TARGET_BRANCH
-    git fetch --depth 1 origin $PAGES_TARGET_BRANCH 
-    git checkout $PAGES_TARGET_BRANCH  
+    git fetch --depth 1 origin $PAGES_TARGET_BRANCH
+    git checkout $PAGES_TARGET_BRANCH
   else
     echo "Creating Pages Branch"
-    git checkout --orphan $PAGES_TARGET_BRANCH 
-    git rm -rf .  
-  fi  
-    
-  #clear out latest and copy site contents to it.  
+    git checkout --orphan $PAGES_TARGET_BRANCH
+    git rm -rf .
+  fi
+
+  #clear out latest and copy site contents to it.
   echo "updating $VERSION_BASE/latest"
-  mkdir -p $PAGES_VERSION_BASE/latest 
+  mkdir -p $PAGES_VERSION_BASE/latest
   rm -rf $PAGES_VERSION_BASE/latest/**./* || exit 0
-  cp -a ../site/. $PAGES_VERSION_BASE/latest 
-  
+  cp -a ../docs/html/. $PAGES_VERSION_BASE/latest
+
   # If a Tagged Build then copy to it's own directory as well.
   if [ -n "$TRAVIS_TAG" ]; then
    echo "Creating $PAGES_VERSION_BASE/$TRAVIS_TAG"
    mkdir -p $PAGES_VERSION_BASE/$TRAVIS_TAG || exit 0
-    cp -a ../site/. $PAGES_VERSION_BASE/$TRAVIS_TAG 
+    cp -a ../docs/html/. $PAGES_VERSION_BASE/$TRAVIS_TAG
   fi
- 
+
   #Check if there are doc changes, if none exit the script
   if [[ -z `git diff --exit-code` ]] && [ -n "$PAGES_BRANCH_EXISTS" ] ; then
     echo "No changes to docs detected."
@@ -84,7 +84,7 @@ if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
 
   #Chganges where detected, so it's safe to write to log.
   now=$(date +"%d %b %Y - %r")
-  export latest=" - [Latest Doc Change]($PAGES_VERSION_BASE/latest/) - Created $now"  
+  export latest=" - [Latest Doc Change]($PAGES_VERSION_BASE/latest/) - Created $now"
   if [ ! -f doc-history.md ]; then
     echo "<!-- Auto generated in .travis/push_docs_to_gh_pages.sh -->" >doc-history.md
     echo "#Doc Generation Log" >>doc-history.md
@@ -93,13 +93,13 @@ if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
     echo "" >>doc-history.md
     echo "##Released Version Doc History" >>doc-history.md
     echo "" >>doc-history.md
-  fi 
+  fi
   if [ -n "$TRAVIS_TAG" ]; then
     echo " - [$TRAVIS_TAG]($PAGES_VERSION_BASE/$TRAVIS_TAG/) - Created $now" >>doc-history.md
-  fi  
-  
+  fi
+
   #replace 4th line in log
-  sed -i '4s@.*@'"$latest"'@'  doc-history.md 
+  sed -i '4s@.*@'"$latest"'@'  doc-history.md
 
   #Setup Git with Commiter info
   git config user.name "Travis CI"
@@ -108,7 +108,7 @@ if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
   #Add and Commit the changes back to pages repo.
   git add .
   git commit -m "Deploy to GitHub Pages: ${SHA}"
-  
+
   #unencrypt and configure deployment key
   [[ -e ../.travis/deploy_key.enc ]] || { echo ".travis/deploy_key.enc file not found";  exit 1; }
   ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key"
@@ -118,9 +118,9 @@ if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
   openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in ../.travis/deploy_key.enc -out  ../.travis/deploy_key -d > /dev/null 2> /dev/null
   chmod 600 ../.travis/deploy_key
   eval `ssh-agent -s`
-  ssh-add ../.travis/deploy_key  
-  
+  ssh-add ../.travis/deploy_key
+
   # Now that we're all set up, we can push.
   echo "git push $SSH_REPO $PAGES_TARGET_BRANCH"
-  git push $SSH_REPO $PAGES_TARGET_BRANCH    
+  git push $SSH_REPO $PAGES_TARGET_BRANCH
 fi

.travis/release/build_docs.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Change working directory to project root
+cd "${UTPLSQL_PROJECT_ROOT}"
+mkdocs build --clean --strict

.travis/release/commit_and_push.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+#inspired by:
+# https://github.com/travis-ci/travis-ci/issues/1476
+# http://stackoverflow.com/questions/36915499/push-to-git-master-branch-from-travis-ci
+current_dir=`pwd`
+commit_message="${1}"
+
+cd "${UTPLSQL_PROJECT_ROOT}"
+
+git config --global user.email "builds@travis-ci.com"
+git config --global user.name "${UTPLSQL_BUILD_USER_NAME}"
+
+echo Adding new/modified/removed files
+git add --all .
+echo Commiting changes
+git commit --quiet -m "${commit_message}"
+echo Pushing
+
+# As suggested here: https://github.com/blog/1270-easier-builds-and-deployments-using-git-over-https-and-oauth
+#   "To avoid writing tokens to disk, don't clone. Instead, just use the full git URL in your push/pull operations (with `.git` suffix)"
+git push --quiet https://${github_api_token}@github.com/${UTPLSQL_REPO}.git HEAD:${CURRENT_BRANCH}
+
+cd "${current_dir}"

.travis/release/create_tag.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+COMMIT_SHA=`git rev-parse HEAD`
+
+#github API documentation: https://developer.github.com/v3/repos/releases/#create-a-release
+#using https://stedolan.github.io/jq/
+curl -H "Authorization: token ${github_api_token}" \
+-X POST --data '{"name":"'${UTPLSQL_VERSION}'","tag_name":"'${UTPLSQL_VERSION}'","target_commitish":"'${COMMIT_SHA}'","prerelease":true' "https://api.github.com/repos/${UTPLSQL_REPO}/releases"

.travis/release/make_release.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+cd "${0%/*}"
+
+#Assumptions:
+# - update project version was executed using update_project_version.sh
+# - docs were build and committed using build_docs.sh
+
+echo Committing project version update and html docs
+. ./commit_and_push.sh "Updated project version (${UTPLSQL_VERSION}) and added html docs [skip ci]"
+
+echo Creating a release tag "${UTPLSQL_VERSION}"
+. ./create_tag.sh
+
+echo Preparing release branch for merge to develop
+echo Removing generated html doc
+rm -rf ${UTPLSQL_PROJECT_ROOT}/docs/html
+
+echo Committing html docs cleanup
+. ./commit_and_push.sh "Cleanup of release of version (${UTPLSQL_VERSION}) [skip ci]"

.travis/release/readme.md

@@ -0,0 +1,33 @@
+#Creating a release
+
+To build a new release from a branch of utPLSQL project do the following:
+
+- Decide on the version number to be created follow the [semantic versioning](http://semver.org/)
+- Create a new branch named in one of the following formats:
+   - `release/vMAJOR.MINOR.PATCH`
+   - `release/vMAJOR.MINOR.PATCH-alpha`
+   - `release/vMAJOR.MINOR.PATCH-beta`
+   - `release/vMAJOR.MINOR.PATCH-something`
+
+The naming convention is there to instruct Travis to do a release from build on that branch.
+
+Version to be built is extracted from the branch name.
+
+The list of project files to be excluded from a release is controlled by content of `.gitattributes` file.
+
+
+#The Release build
+
+Release build is performing all the activities of regular build and additionally dose the following:
+- Cleans the working copy
+- Updates all project files with new version number 
+- Generates html documentation
+- Commits and pushes
+- Creates a release tag and publishes the release artifacts
+- Removes generated documentation
+- Commits and pushes
+
+
+#Post release tasks
+
+Once the release is published, it is recommended to merge it to the develop branch and delete it after.

.travis/release/update_project_version.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+echo Updating version in project source files
+find ${UTPLSQL_SOURCES_DIR} -type f -name '*' -exec sed -i -r "s/(${UTPLSQL_VERSION_PLACEHOLDER} )[^']*(')?/\1${UTPLSQL_VERSION}\2/" {} \;
+
+echo Update of sonar-project.properties sonar.projectVersion
+sed -i -r "s/(sonar\.projectVersion=).*?/\1${UTPLSQL_VERSION}/" sonar-project.properties
+echo Setting project version in VERSION file
+echo ${UTPLSQL_VERSION} > VERSION