Merge branch 'enhancement/build-release'

.gitignore

@@ -10,6 +10,10 @@ desktop.ini
 .DS_Store
 ._*
 
+# Travis
+/build/phpdoc-*/
+/build/phpdoc-*.git/
+
 # Composer
 /composer.lock
 /composer.phar

.travis.yml

@@ -13,14 +13,24 @@ matrix:
     - php: nightly
   fast-finish: true
 
+install:
+  - composer install
+
+before_script:
+  - export PATH="$TRAVIS_BUILD_DIR/build:$TRAVIS_BUILD_DIR/vendor/bin:$PATH"
+
 script:
-  - find . -not \( -path './vendor' -prune \) -type f -name '*.php' -print0 | xargs -0 -I file php -l file > /dev/null
+  - phpcs --standard=phpcs.xml "$TRAVIS_BUILD_DIR"
+
+after_success:
+  - deploy-phpdoc-branch.sh
 
 before_deploy:
-  - composer install
-  - composer dump-autoload --optimize
+  - deploy-phpdoc-release.sh
+  - composer install --no-dev --optimize-autoloader
   - find vendor/ -type d -path 'vendor/*/*/.git' -print0 | xargs -0 rm -rf
-  - tar -czf "pico-release-$TRAVIS_TAG.tar.gz" .htaccess README.md CHANGELOG.md CONTRIBUTING.md composer.json composer.lock LICENSE config content-sample lib plugins themes vendor index.php
+  - mv index.php.dist index.php
+  - tar -czf "pico-release-$TRAVIS_TAG.tar.gz" README.md LICENSE CONTRIBUTING.md CHANGELOG.md composer.json composer.lock config content-sample lib plugins themes vendor .htaccess index.php
 
 deploy:
   provider: releases
@@ -32,4 +42,3 @@ deploy:
     php: 5.3
 
 sudo: false
-

CONTRIBUTING.md

@@ -12,7 +12,9 @@ Issues
 
 If you want to report an *issue* with Pico's core, please create a new [Issue](https://github.com/picocms/Pico/issues) on GitHub. Concerning problems with plugins or themes, please refer to the website of the developer of this plugin or theme.
 
-Before creating a [new Issue on GitHub](https://github.com/picocms/Pico/issues/new), please make sure the problem wasn't reported yet using [GitHubs search engine](https://github.com/picocms/Pico/search?type=Issues). Please describe your issue as clear as possible and always include steps to reproduce the problem.
+Before creating a [new Issue on GitHub](https://github.com/picocms/Pico/issues/new), please make sure the problem wasn't reported yet using [GitHubs search engine](https://github.com/picocms/Pico/search?type=Issues).
+
+Please describe your issue as clear as possible and always include the *Pico version* you're using. Provided that you're using *plugins*, include a list of them too. We need information about the *actual and expected behavior*, the *steps to reproduce* the problem, and what steps have you taken to resolve the problem by yourself (i.e. *your own troubleshooting*)?
 
 Contributing code
 -----------------
@@ -78,44 +80,18 @@ As soon as development reaches a point where feedback is appreciated, a pull req
 Build & Release process
 -----------------------
 
-This is work in progress. Please refer to [#268](https://github.com/picocms/Pico/issues/268) for details.
+We're using [Travis CI](https://travis-ci.com) to automate the build & release process of Pico. It generates and deploys [phpDoc](http://phpdoc.org) class docs for new releases and on every commit to the `master` branch. Travis also prepares new releases by generating Pico's pre-built packages and uploading them to GitHub. Please refer to [our `.travis.yml`](https://github.com/picocms/Pico/blob/master/.travis.yml) for details.
 
-<!--
+As insinuated above, it is important that each commit to `master` is deployable. Once development of a new Pico release is finished, trigger Pico's build & release process by pushing a new Git tag. This tag should reference a (usually empty) commit on `master`, which message should adhere to the following template:
 
-Defined below is a specification to which the Build and Release process of Pico should follow. We use `travis-ci` to automate the process, and each commit to `master` should be releasable.
+```
+Version 1.0.0
 
-#### Commit phase
-- Commit changes
-- Create & Push Git tag
-- Trigger automatic build process...
+* [Security] ...
+* [New] ...
+* [Changed] ...
+* [Fixed] ...
+* [Removed] ...
+```
 
-Example commit message:
-
-    Pico 1.0.1
-    * [New] ...
-    * [Changed] ...
-
-*Please submit pull-requests with a properly
-formatted commit message/SemVer increase to avoid the need for manual amendments.*
-
-#### Analysis phase
-- Run through `scrutinizer-ci`?
-
-#### Packaging phase
-- Run composer locally
-- Create a ZIP archive (so vendor/ is included)
-- Build documentation, output goes to a new folder in the `gh-pages` branch
-
-#### Release phase
-- Create new Git release at tag
-- Upload ZIP archive
-- Upload documentation to the `gh-pages` branch
-- Set Symlink for latest documentation (http://picocms.org/docs/latest)
-- Update release information on GitHub with:
-    - Release title (taken from changelog)
-    - Changelog
-
-#### Announcements
-- Where to announce new Pico release?
-
--->
+Travis CI will draft the new [release on GitHub](https://github.com/picocms/Pico/releases) automatically, but will require you to manually amend the descriptions formatting. The latest Pico version is always available at https://github.com/picocms/Pico/releases/latest, so please make sure to publish this URL rather than version-specific URLs. [Packagist](http://packagist.org/packages/picocms/pico) will be updated automatically.

build/deploy-phpdoc-branch.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+if [ "$TRAVIS_PHP_VERSION" != "5.3" ]; then
+    echo "Skipping phpDoc deployment because this is not on the required runtime"
+    exit
+fi
+
+if [[ ",$DEPLOY_PHPDOC_BRANCHES," != *,"$TRAVIS_BRANCH",* ]]; then
+    echo "Skipping phpDoc deployment because this branch ($TRAVIS_BRANCH) is not permitted to deploy"
+    exit
+fi
+
+if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then
+    echo "Skipping phpDoc deployment because this pull request (#$TRAVIS_PULL_REQUEST) is not permitted to deploy"
+    exit
+fi
+
+PHPDOC_ID="${TRAVIS_BRANCH//\//_}"
+
+generate-phpdoc.sh \
+    "$TRAVIS_BUILD_DIR" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "Pico 1.0 API Documentation ($TRAVIS_BRANCH branch)"
+[ $? -eq 0 ] || exit 1
+
+deploy-phpdoc.sh \
+    "$TRAVIS_REPO_SLUG" "heads/$TRAVIS_BRANCH @ $TRAVIS_COMMIT" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "$TRAVIS_REPO_SLUG" "gh-pages" "phpDoc/$PHPDOC_ID"
+[ $? -eq 0 ] || exit 1

build/deploy-phpdoc-release.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+[ "$DEPLOY_PHPDOC_RELEASES" == "true" ] || exit
+
+PHPDOC_ID="${TRAVIS_BRANCH//\//_}"
+
+generate-phpdoc.sh \
+    "$TRAVIS_BUILD_DIR" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "Pico 1.0 API Documentation ($TRAVIS_TAG)"
+[ $? -eq 0 ] || exit 1
+
+deploy-phpdoc.sh \
+    "$TRAVIS_REPO_SLUG" "tags/$TRAVIS_TAG" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "$TRAVIS_REPO_SLUG" "gh-pages" "phpDoc/$PHPDOC_ID"
+[ $? -eq 0 ] || exit 1

build/deploy-phpdoc.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -e
+
+# base variables
+APP_NAME="$(basename "$0")"
+BASE_PWD="$PWD"
+
+# environment variables
+# GITHUB_OAUTH_TOKEN    GitHub authentication token, see https://github.com/settings/tokens
+
+# parameters
+SOURCE_REPO_SLUG="$1"       # source GitHub repo (e.g. picocms/Pico)
+SOURCE_REF="$2"             # source reference (either "[ref] @ [commit]" or "[ref]",
+                            #                   [ref] can be e.g. heads/master or tags/v1.0.0)
+SOURCE_DIR="$3"             # absolute source path
+TARGET_REPO_SLUG="$4"       # target GitHub repo (e.g. picocms/Pico)
+TARGET_BRANCH="$5"          # target branch (e.g. gh-pages)
+TARGET_DIR="$6"             # relative target path
+
+# print parameters
+echo "Deploying phpDocs..."
+printf 'SOURCE_REPO_SLUG="%s"\n' "$SOURCE_REPO_SLUG"
+printf 'SOURCE_REF="%s"\n' "$SOURCE_REF"
+printf 'SOURCE_DIR="%s"\n' "$SOURCE_DIR"
+printf 'TARGET_REPO_SLUG="%s"\n' "$TARGET_REPO_SLUG"
+printf 'TARGET_BRANCH="%s"\n' "$TARGET_BRANCH"
+printf 'TARGET_DIR="%s"\n' "$TARGET_DIR"
+echo
+
+# evaluate source reference
+if [[ "$SOURCE_REF" == *" @ "* ]]; then
+    SOURCE_REF_TYPE="commit"
+    SOURCE_REF_HEAD="${SOURCE_REF% @ *}"
+    SOURCE_REF_COMMIT="${SOURCE_REF##* @ }"
+
+    if ! git check-ref-format "$SOURCE_REF_HEAD" || ! git rev-parse --verify "$SOURCE_REF_COMMIT" > /dev/null; then
+        echo "FATAL: $APP_NAME source reference '$SOURCE_REF' is invalid" >&2
+        exit 1
+    fi
+elif git check-ref-format "$SOURCE_REF"; then
+    SOURCE_REF_TYPE="ref"
+else
+    echo "FATAL: $APP_NAME source reference '$SOURCE_REF' is invalid" >&2
+    exit 1
+fi
+
+# clone repo
+printf 'Cloning repo...\n'
+GIT_DIR="$SOURCE_DIR.git"
+git clone --branch="$TARGET_BRANCH" "https://github.com/$TARGET_REPO_SLUG.git" "$GIT_DIR"
+
+# setup git
+cd "$GIT_DIR"
+git config user.name "Travis CI"
+git config user.email "travis-ci@picocms.org"
+
+if [ -n "$GITHUB_OAUTH_TOKEN" ]; then
+    git config credential.helper 'store --file=.git/credentials'
+    (umask 077 && echo "https://GitHub:$GITHUB_OAUTH_TOKEN@github.com" > .git/credentials)
+fi
+
+# copy phpdoc
+printf '\nCopying phpDocs...\n'
+[ ! -d "$TARGET_DIR" ] || rm -rf "$TARGET_DIR"
+[ "${SOURCE_DIR:0:1}" == "/" ] || SOURCE_DIR="$BASE_PWD/$SOURCE_DIR"
+cp -R "$SOURCE_DIR" "$TARGET_DIR"
+
+# commit changes
+printf '\nCommiting changes...\n'
+git add --all "$TARGET_DIR"
+git commit --message="Update phpDocumentor class docs for $SOURCE_REF"
+
+# very simple race condition protection for concurrent Travis builds
+# this is no definite protection (race conditions are still possible during `git push`),
+# but it should give a basic protection without disabling concurrent builds completely
+if [ "$SOURCE_REF_TYPE" == "commit" ]; then
+    # load branch data via GitHub APIv3
+    printf '\nRetrieving latest commit...\n'
+    LATEST_COMMIT_URL="https://api.github.com/repos/$SOURCE_REPO_SLUG/git/refs/$SOURCE_REF_HEAD"
+    if [ -n "$GITHUB_OAUTH_TOKEN" ]; then
+        LATEST_COMMIT_RESPONSE="$(wget -O- --header="Authorization: token $GITHUB_OAUTH_TOKEN" "$LATEST_COMMIT_URL" 2> /dev/null)"
+    else
+        LATEST_COMMIT_RESPONSE="$(wget -O- "$LATEST_COMMIT_URL" 2> /dev/null)"
+    fi
+
+    # evaluate JSON response
+    LATEST_COMMIT="$(echo "$LATEST_COMMIT_RESPONSE" | php -r "
+        \$json = json_decode(stream_get_contents(STDIN), true);
+        if (\$json !== null) {
+            if (isset(\$json['ref']) && (\$json['ref'] === 'refs/$SOURCE_REF_HEAD')) {
+                if (isset(\$json['object']) && isset(\$json['object']['sha'])) {
+                    echo \$json['object']['sha'];
+                }
+            }
+        }
+    ")"
+
+    # compare source reference against the latest commit
+    if [ "$LATEST_COMMIT" != "$SOURCE_REF_COMMIT" ]; then
+        echo "WARNING: $APP_NAME source reference '$SOURCE_REF' doesn't match the latest commit '$LATEST_COMMIT'" >&2
+        exit 0
+    fi
+fi
+
+# push changes
+printf '\nPushing changes...\n'
+git push "https://github.com/$TARGET_REPO_SLUG.git" "$TARGET_BRANCH:$TARGET_BRANCH"
+
+echo

build/generate-phpdoc.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -e
+
+# parameters
+PHPDOC_SOURCE_DIR="$1"
+PHPDOC_TARGET_DIR="$2"
+PHPDOC_TITLE="$3"
+
+# print parameters
+echo "Generating phpDocs..."
+printf 'PHPDOC_SOURCE_DIR="%s"\n' "$PHPDOC_SOURCE_DIR"
+printf 'PHPDOC_TARGET_DIR="%s"\n' "$PHPDOC_TARGET_DIR"
+printf 'PHPDOC_TITLE="%s"\n' "$PHPDOC_TITLE"
+echo
+
+# generate phpdoc
+phpdoc -d "$PHPDOC_SOURCE_DIR" \
+    -i "$PHPDOC_SOURCE_DIR/build/" \
+    -i "$PHPDOC_SOURCE_DIR/vendor/" \
+    -i "$PHPDOC_SOURCE_DIR/plugins/" -f "$PHPDOC_SOURCE_DIR/plugins/DummyPlugin.php" \
+    -t "$PHPDOC_TARGET_DIR" \
+    --title "$PHPDOC_TITLE"
+
+echo

composer.json

@@ -28,6 +28,10 @@
         "erusev/parsedown-extra": "^0.7",
         "symfony/yaml" : "^2.3"
     },
+    "require-dev" : {
+        "phpdocumentor/phpdocumentor": "^2.8",
+        "squizlabs/php_codesniffer": "^2.4"
+    },
     "autoload": {
         "psr-0": {
             "Pico": "lib/",

index.php

@@ -1,9 +1,4 @@
-<?php
-
-// check PHP version
-if (version_compare(PHP_VERSION, '5.3.6', '<')) {
-    die('Sorry, Pico requires PHP 5.3.6 or above to run!');
-}
+<?php // @codingStandardsIgnoreFile
 
 // load dependencies
 if(is_file(__DIR__ . '/vendor/autoload.php')) {
@@ -25,7 +20,7 @@ $pico = new Pico(
 );
 
 // override configuration?
-// $pico->setConfig(array());
+//$pico->setConfig(array());
 
 // run application
 echo $pico->run();

index.php.dist

@@ -0,0 +1,20 @@
+<?php // @codingStandardsIgnoreFile
+
+// check PHP version
+if (version_compare(PHP_VERSION, '5.3.6', '<')) {
+    die('Pico requires PHP 5.3.6 or above to run');
+}
+
+// load dependencies
+require_once(__DIR__ . '/vendor/autoload.php');
+
+// instance Pico
+$pico = new Pico(
+    __DIR__,    // root dir
+    'config/',  // config dir
+    'plugins/', // plugins dir
+    'themes/'   // themes dir
+);
+
+// run application
+echo $pico->run();

phpcs.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+<ruleset name="Pico">
+    <description>
+        Pico's coding standards mainly base on the PHP-FIG PSR-2 standard,
+        but without the MissingNamespace sniff.
+    </description>
+
+    <!--
+        Exclude build/ and vendor/ dirs as well as minified JavaScript files
+    -->
+    <exclude-pattern type="relative">^build/</exclude-pattern>
+    <exclude-pattern type="relative">^vendor/</exclude-pattern>
+    <exclude-pattern>*.min.js</exclude-pattern>
+
+    <!--
+        Check files for PHP syntax errors
+    -->
+    <config name="php_path" value="php"/>
+    <rule ref="Generic.PHP.Syntax"/>
+
+    <!--
+        Never use deprecated functions,
+        as they will be removed in future PHP releases
+    -->
+    <rule ref="Generic.PHP.DeprecatedFunctions"/>
+
+    <!--
+        Warn about structures which affect performance negatively
+    -->
+    <rule ref="Generic.CodeAnalysis.ForLoopWithTestFunctionCall"/>
+
+    <!--
+        Pico follows PHP-FIG PSR-2 Coding Style,
+        but doesn't use formal namespaces for historic reasons
+    -->
+    <rule ref="PSR2">
+        <exclude name="PSR1.Classes.ClassDeclaration.MissingNamespace"/>
+    </rule>
+</ruleset>