Merge pull request #1231 from jim-parry/admin/build

Release build script

.gitignore

@@ -131,3 +131,4 @@ nb-configuration.xml
 
 /results/
 /phpunit*.xml
+

admin/docbot.md

@@ -24,7 +24,7 @@ GPG-signing key as appropriate.
 
 Inside a shell prompt, in the project root:
 
-    `admin/docbot.sh [deploy]`
+    `admin/docbot [deploy]`
 
 If "deploy" is not added, the script execution is considered
 a trial run, and nothing is pushed to the repo.

admin/release

@@ -0,0 +1,179 @@
+#~/bin/bash
+
+## Build and deploy framework release
+
+UPSTREAM=https://github.com/bcit-ci/CodeIgniter4.git
+action=test
+version=4
+qualifier=
+
+branch=release-
+devonly='.github/* admin/* build/* contributing/* user_guide_src/* CODE_OF_CONDUCT.md \
+DCO.txt PULL_REQUEST_TEMPLATE.md'
+which=release
+
+BOLD='\033[1m'
+NORMAL='\033[0m'
+COLOR='\033[1;31m'
+ERROR='\033[0;31m'
+
+echo -e "${BOLD}${COLOR}CodeIgniter4 release builder${NORMAL}"
+echo '----------------------------'
+
+#---------------------------------------------------
+# Check arguments
+echo -e "${BOLD}Checking arguments...${NORMAL}"
+
+if [ $# -lt 1 ]; then
+    echo "You really need to read the directions first!"
+    exit 1
+fi
+
+if [ $1 = 'deploy' ]; then
+    action=deploy
+elif [ $1 != 'test' ]; then
+    echo -e "${ERROR}Invalid action ($1)${NORMAL}"
+    exit 1
+fi
+shift   # drop the command from the argument list
+
+version=$1
+if [ $# -gt 1 ]; then
+    qualifier="-${2}"
+    which='pre-release'
+fi
+branch="release-$version$qualifier"
+
+#---------------------------------------------------
+# Create the release branch
+echo -e "${BOLD}Creating $which $branch to $action ${NORMAL}"
+
+git checkout develop
+git branch -d $branch     # remove the branch if there
+git checkout -b $branch
+
+#---------------------------------------------------
+# Update version dependencies
+echo -e "${BOLD}Updating version dependencies${NORMAL}"
+
+function check_unique {
+    count=`grep -c '$1' < $2 | wc -l`
+    if [ $count -ne 1 ]; then
+        echo -e "${BOLD}${COLOR}$2 has ${count} occurences of '$1'${NORMAL}"
+        exit 1
+    fi
+}
+
+# Make sure there is only one line to affect in each file
+check_unique "const CI_VERSION" 'system/CodeIgniter.php'
+check_unique "release =" 'user_guide_src/source/conf.py'
+check_unique "|release|" 'user_guide_src/source/changelog.rst'
+check_unique "Release Date.*Not Released" 'user_guide_src/source/changelog.rst'
+
+# CI_VERSION definition in system/CodeIgniter.php
+sed -i "/const CI_VERSION/s/'.*'/'${version}${qualifier}'/" system/CodeIgniter.php
+
+# release substitution variable in user_guide_src/source/conf.py
+sed -i "/release =/s/'.*'/'${version}${qualifier}'/" user_guide_src/source/conf.py
+
+# version & date in user_guide_src/source/changelog.rst
+sed -i "/|release|/s/|.*|/${version}${qualifier}/" user_guide_src/source/changelog.rst
+sed -i "/Release Date/s/Not Released/$(date +'%B %d, %Y')/" user_guide_src/source/changelog.rst
+
+#---------------------------------------------------
+# Generate the user guide
+echo -e "${BOLD}Generate the user guide${NORMAL}"
+cd user_guide_src
+
+# make the UG & embed it in the project root
+make html
+rm -Rf ../docs
+mv build/html ../docs
+
+# make the epub, but leave it inside the gitignored user_guide_src to deal with separately
+make epub
+
+cd ..
+
+#---------------------------------------------------
+# Hide stuff from the release bundle
+echo -e "${BOLD}Hide stuff from the release bundle${NORMAL}"
+
+# Restore the old .gitignore 
+if [ -f admin/previous-gitignore ]; then
+    cp -r admin/previous-gitignore .gitignore
+fi
+cp -r .gitignore admin/previous-gitignore
+
+# Add the dev only folders/files to .gitignore
+for f in $devonly; do
+    echo $f >> .gitignore
+done
+
+#---------------------------------------------------
+# And finally, the release tag
+echo -e "${BOLD}Tag this branch for release${NORMAL}"
+git add .
+git commit -m "Release ${version}${qualifier}"
+git tag -a v${version}${qualifier} -m "Release ${version}${qualifier} build"
+
+#---------------------------------------------------
+# Are we there yet?
+if [ $action = 'test' ]; then
+    echo -e "${BOLD}Your $branch branch is ready to inspect.${NORMAL}"
+    exit 0
+fi
+echo -e "${BOLD}Are we there yet (yes|no)?${NORMAL}"
+read answer
+if [ $answer != 'yes' ]; then
+    echo -e "${BOLD}Your $branch branch is ready to inspect.${NORMAL}"
+    echo "Rerun this script when ready to deploy"
+    exit 1
+fi
+
+#---------------------------------------------------
+# Merge away
+echo -e "${BOLD}Merge the release into master${NORMAL}"
+git checkout master
+git merge $branch
+git push UPSTREAM master
+git push UPSTREAM --tags
+
+#---------------------------------------------------
+# Put our house back in order
+echo -e "${BOLD}Put our house back in order${NORMAL}"
+
+mv -r admin/previous-gitignore .gitignore
+rm -Rf docs
+
+#---------------------------------------------------
+# Add next version block in changelog.rst
+echo -e "${BOLD}Setup next release${NORMAL}"
+sed -i '5 i\
+Version |release|
+====================================================
+
+Release Date: Not Released
+' user_guide_src/source/changelog.rst
+
+#---------------------------------------------------
+# Merge away
+echo -e "${BOLD}Setup the develop branch${NORMAL}"
+git add .
+git commit -S -m "Post ${branch} cleanup"
+git push origin master
+git push UPSTREAM master
+
+git checkout develop
+git merge master
+git push origin develop
+git push UPSTREAM develop
+
+# keep or delete the release branch? up to you
+#git branch -d $branch
+
+#---------------------------------------------------
+# Phew!
+
+echo -e "${BOLD}Congratulations - we have liftoff${NORMAL}"
+echo "Don't forget to announce this release on the forum and on twitter!"

admin/release.md

@@ -1,8 +1,81 @@
 # release
 
-Builds & deploys framework release.
+Builds & deploys a framework release.
+
+This tool is meant to help automate the process of
+launching a new release, by creating the release
+distribution files, tagging everything properly, 
+and getting the repo branches in order.
+
+## Audience
+
+This script is intended for use by framework maintainers,
+i.e. someone with commit rights on the CI4 repository.
+
+You will be prompted for your github credentials and
+GPG-signing key as appropriate.
+
+## Workflow
+
+The repo has two branches of interest: "master" (stable) and "develop" (in progress).
+There might be other feature branches, but they are not relevant to this process.
+
+Once "develop" is ready for a new release, the general workflow is to
+
+- create a release branch from develop
+- update version dependencies or constants
+- generate version(s) of the user guide
+- move or ignore stuff, distinguishing release from development
+- test that all is as it should be
+- tag and merge the release branch into "master"
+- merge "master" into "develop"
+- put everything back where it should be for development
+- remove the release branch
+
+Visually:
+
+    develop -> release -> master -> develop
+
+Finally, there are a couple of manual tasks:
+
+- post a sticky announcement thread on the forum
+- tweet the release announcement
 
 ## Assumptions
 
+You (a maintainer) have forked the main CodeIgniter4 repo,
+and the git alias `origin`, in your local clone, refers to your fork. 
+The script creates an additional alias, `upstream`, which refers to the 
+main repo. This separation keeps the release branch isolated
+for any testing you want to do.
+
+The `develop` branch of the main repo should be "clean", and ready for
+a release. This means that the changelog and upgrading instructions
+have been suitably edited.
+
+This script is not intended to deal with hotfixes, i.e. PRs against
+`master` that need to also be merged into `develop`, probably
+as part of a bug fix minor release.
+
 ## Usage
 
+Inside a shell prompt, in the project root:
+
+    `admin/release [test|deploy] version [qualifier]`
+
+If the "deploy" action is not specified, the script execution is considered
+a trial run, and nothing is pushed to the repo. 
+Whether or not deployed, the results are left inside
+the release branch in your local clone.
+
+The "version" should follow semantic versioning, e.g. `4.0.6`, and the
+version number should be higher than the current released one.
+
+The "qualifier" argument is a suffix to add to the version
+for a pre-release, e.g. `beta.2` or `rc.41`.
+
+Examples:
+- `admin/release test 4.0.0 alpha.1` would prepare the "4.0.0-alpha.1" pre-release PR
+- `admin/release 4.0.0` would prepare the "4.0.0" release PR
+- `admin/release peanut butter banana` would complain and tell you to read these directions
+

user_guide_src/source/changelog.rst

@@ -2,13 +2,13 @@
 Change Log
 ##########
 
-Version |version|
+Version |release|
 =================
 
-**Rewrite of the CodeIgniter framework**
-
 Release Date: Not Released
 
+**Rewrite of the CodeIgniter framework**
+
 New core classes:
     - CodeIgniter (bootstrap)
     - Common (shared functions)

user_guide_src/source/conf.py

@@ -50,7 +50,7 @@
 # The short X.Y version.
 version = '4.0-dev'
 # The full version, including alpha/beta/rc tags.
-release = '4.0.0-not'
+release = '4.0.0-alpha.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -60,7 +60,7 @@
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.