Merge branch 'release/1.0.0-alpha8'

.travis.yml

@@ -33,9 +33,9 @@ matrix:
     - { name: "Deprecated code scan w/ dependencies", env: ORCA_JOB=DEPRECATED_CODE_SCAN_CONTRIB }
     - { name: "Isolated test w/ recommended package versions", env: ORCA_JOB=ISOLATED_RECOMMENDED }
     - { name: "Integrated test w/ recommended package versions", env: ORCA_JOB=INTEGRATED_RECOMMENDED }
+    - { name: "Previous minor version of Drupal core", env: ORCA_JOB=CORE_PREVIOUS }
     - { name: "Isolated test w/ dev package versions", env: ORCA_JOB=ISOLATED_DEV }
     - { name: "Integrated test w/ dev package versions", env: ORCA_JOB=INTEGRATED_DEV }
-    - { name: "Previous minor version of Drupal core", env: ORCA_JOB=CORE_PREVIOUS }
     - { name: "Next pre-release of Drupal core", env: ORCA_JOB=CORE_NEXT }
   allow_failures:
     - env: ORCA_JOB=DEPRECATED_CODE_SCAN_CONTRIB

bin/travis/_includes.sh

@@ -34,6 +34,12 @@ export ORCA_ROOT="$(cd "$(dirname "$BASH_SOURCE")/../.." && pwd)"
 export ORCA_FIXTURE_DIR=${ORCA_FIXTURE_DIR:="${ORCA_ROOT}/../orca-build"}
 export ORCA_SUT_DIR=${ORCA_SUT_DIR:=${TRAVIS_BUILD_DIR}}
 
+# Add binary directories to PATH.
+export PATH="$HOME/.composer/vendor/bin:$PATH"
+export PATH="$ORCA_ROOT/bin:$PATH"
+export PATH="$ORCA_ROOT/vendor/bin:$PATH"
+export PATH="$ORCA_FIXTURE_DIR/vendor/bin:$PATH"
+
 # Exit as soon as one command returns a non-zero exit code and make the shell
 # print all lines in the script before executing them.
 # @see https://docs.travis-ci.com/user/job-lifecycle/#complex-build-commands

bin/travis/after_failure.sh

@@ -12,5 +12,5 @@
 cd "$(dirname "$0")"; source _includes.sh
 
 if [[ -f "$ORCA_FIXTURE_DIR/vendor/bin/drush" ]]; then
-  "$ORCA_FIXTURE_DIR/vendor/bin/drush" watchdog:show --count=100 --severity=Error --extended
+  drush watchdog:show --count=100 --severity=Error --extended
 fi

bin/travis/install.sh

@@ -13,18 +13,18 @@ cd "$(dirname "$0")"; source _includes.sh
 
 assert_env_vars
 
-[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_SUT" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only
+[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_SUT" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only
 
-[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_CONTRIB" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only
+[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_CONTRIB" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only
 
-[[ "$ORCA_JOB" != "ISOLATED_RECOMMENDED" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only
+[[ "$ORCA_JOB" != "ISOLATED_RECOMMENDED" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only
 
-[[ "$ORCA_JOB" != "INTEGRATED_RECOMMENDED" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME}
+[[ "$ORCA_JOB" != "INTEGRATED_RECOMMENDED" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME}
 
-[[ "$ORCA_JOB" != "ISOLATED_DEV" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only --dev
+[[ "$ORCA_JOB" != "CORE_PREVIOUS" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME} --core=PREVIOUS_MINOR
 
-[[ "$ORCA_JOB" != "INTEGRATED_DEV" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME} --dev
+[[ "$ORCA_JOB" != "ISOLATED_DEV" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME} --sut-only --dev
 
-[[ "$ORCA_JOB" != "CORE_PREVIOUS" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME} --core=PREVIOUS_MINOR
+[[ "$ORCA_JOB" != "INTEGRATED_DEV" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME} --dev
 
-[[ "$ORCA_JOB" != "CORE_NEXT" ]] || ../orca fixture:init -f --sut=${ORCA_SUT_NAME} --core=LATEST_PRERELEASE --dev
+[[ "$ORCA_JOB" != "CORE_NEXT" ]] || orca fixture:init -f --sut=${ORCA_SUT_NAME} --core=LATEST_PRERELEASE --dev

bin/travis/script.sh

@@ -13,22 +13,22 @@ cd "$(dirname "$0")"; source _includes.sh
 
 assert_env_vars
 
-[[ ! -d "$ORCA_FIXTURE_DIR" ]] || ../orca fixture:status
+[[ ! -d "$ORCA_FIXTURE_DIR" ]] || orca fixture:status
 
-[[ "$ORCA_JOB" != "STATIC_CODE_ANALYSIS" ]] || ../orca static-analysis:run ${ORCA_SUT_DIR}
+[[ "$ORCA_JOB" != "STATIC_CODE_ANALYSIS" ]] || orca static-analysis:run ${ORCA_SUT_DIR}
 
-[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_SUT" ]] || ../orca deprecated-code-scan:run --sut=${ORCA_SUT_NAME}
+[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_SUT" ]] || orca deprecated-code-scan:run --sut=${ORCA_SUT_NAME}
 
-[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_CONTRIB" ]] || ../orca deprecated-code-scan:run --contrib
+[[ "$ORCA_JOB" != "DEPRECATED_CODE_SCAN_CONTRIB" ]] || orca deprecated-code-scan:run --contrib
 
-[[ "$ORCA_JOB" != "ISOLATED_RECOMMENDED" ]] || ../orca tests:run --sut=${ORCA_SUT_NAME} --sut-only
+[[ "$ORCA_JOB" != "ISOLATED_RECOMMENDED" ]] || orca tests:run --sut=${ORCA_SUT_NAME} --sut-only
 
-[[ "$ORCA_JOB" != "INTEGRATED_RECOMMENDED" ]] || ../orca tests:run --sut=${ORCA_SUT_NAME}
+[[ "$ORCA_JOB" != "INTEGRATED_RECOMMENDED" ]] || orca tests:run --sut=${ORCA_SUT_NAME}
 
-[[ "$ORCA_JOB" != "ISOLATED_DEV" ]] || ../orca tests:run --sut=${ORCA_SUT_NAME} --sut-only
+[[ "$ORCA_JOB" != "CORE_PREVIOUS" ]] || orca tests:run --sut=${ORCA_SUT_NAME}
 
-[[ "$ORCA_JOB" != "INTEGRATED_DEV" ]] || ../orca tests:run --sut=${ORCA_SUT_NAME}
+[[ "$ORCA_JOB" != "ISOLATED_DEV" ]] || orca tests:run --sut=${ORCA_SUT_NAME} --sut-only
 
-[[ "$ORCA_JOB" != "CORE_PREVIOUS" ]] || ../orca tests:run --sut=${ORCA_SUT_NAME}
+[[ "$ORCA_JOB" != "INTEGRATED_DEV" ]] || orca tests:run --sut=${ORCA_SUT_NAME}
 
-[[ "$ORCA_JOB" != "CORE_NEXT" ]] || ../orca tests:run --sut=${ORCA_SUT_NAME}
+[[ "$ORCA_JOB" != "CORE_NEXT" ]] || orca tests:run --sut=${ORCA_SUT_NAME}

config/VERSION

@@ -1 +1 @@
-v1.0.0-alpha7
+v1.0.0-alpha8

config/packages.yml

@@ -27,12 +27,6 @@
 # or merged in using the "ORCA_PACKAGES_CONFIG_ALTER" environment variable. See
 # config/services.yml for the relevant code or bin/self-test for a usage
 # example.
-acquia/acsf-tools:
-  type: drupal-drush
-  # acsf-tools specifies an installer-name.
-  install_path: drush/Commands/acsf_tools
-  version_dev: dev-9.x-dev
-
 #drupal/acquia_commercemanager:
 #  url: ../commerce-manager
 #  version_dev: 1.x-dev

docs/getting-started.md

@@ -49,10 +49,10 @@ Invoke ORCA from the terminal (`bin/orca`). Use the `--help` command option to l
 
 ORCA uses tags (for Behat) and groups (for PHPUnit) to determine which tests to run when, as depicted in the table below, where black indicates a test's being included and white indicates its being ignored:
 
-| | (Default) | `orca_public` | `orca_ignore` |
-| --- | :---: | :---: | :---: |
-| Isolated tests (own) | :black_circle: | :black_circle: | :white_circle: |
-| Integrated tests (own) | :black_circle: | :black_circle: | :white_circle: |
+|                            |    (Default)   |  `orca_public` |  `orca_ignore` |
+|----------------------------|:--------------:|:--------------:|:--------------:|
+| Isolated tests (own)       | :black_circle: | :black_circle: | :white_circle: |
+| Integrated tests (own)     | :black_circle: | :black_circle: | :white_circle: |
 | Integrated tests (others') | :white_circle: | :black_circle: | :white_circle: |
 
 The default behavior is to run a test only when the package providing it is the SUT--not when it is merely included in another package's test fixture. Any test not designated public or ignored is so treated. Such tests are referred to as "private tests". This should be considered the correct choice for most tests--particularly for features that involve little or no risk of conflict with other Acquia packages, including [isolated unit tests](http://wiki.c2.com/?UnitTestIsolation) by definition.

docs/understanding-orca.md

@@ -61,14 +61,15 @@ See [Designing automated tests](getting-started.md#designing-automated-tests).
 
 ORCA includes out-of-the-box support for Travis CI for continuous integration. The default implementation runs the following concurrent jobs per build:
 
-| | Static code<br /> analysis | Deprecated<br /> code scan<br /> w/ SUT | Deprecated<br /> code scan w/<br /> dependencies | Integrated/<br /> recommended | Isolated/<br /> recommended | Integrated/<br /> dev | Isolated/<br /> dev |
-| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
-| Fixture type | None | SUT-only | SUT-only | SUT-only | SUT-only | Standard | Standard |
-| Package stability | n/a | Stable | Stable | Stable | Stable | Dev | Dev |
-| Static analysis | :black_circle: | :white_circle: | :white_circle: | :white_circle: | :white_circle: | :white_circle: | :white_circle: |
-| Deprecated code scan | :white_circle: | :black_circle: | :black_circle: | :white_circle: | :white_circle: | :white_circle: | :white_circle: |
-| Automated tests | :white_circle: | :white_circle: | :white_circle: | :black_circle: | :black_circle: | :black_circle: | :black_circle: |
-| Allow failure | :white_circle: | :white_circle: | :white_circle: | :white_circle: | :white_circle: | :black_circle: | :black_circle: |
+|                      | #1<br />Static code<br />analysis | #2<br />Deprecated<br />code scan<br />w/ SUT | #3<br />Deprecated<br />code scan w/<br />dependencies | #4<br />Isolated/<br />recommended | #5<br />Integrated/<br />recommended | #6<br />Previous core<br />version | #7<br />Isolated/<br />dev | #8<br />Integrated/<br />dev | #9<br />Next core<br />version |
+|----------------------|:---------------------------------:|:---------------------------------------------:|:------------------------------------------------------:|:----------------------------------:|:------------------------------------:|:----------------------------------:|:--------------------------:|:----------------------------:|:------------------------------:|
+| Fixture type         |                None               |                    SUT-only                   |                        SUT-only                        |              SUT-only              |               Standard               |              Standard              |          SUT-only          |           Standard           |            Standard            |
+| Package stability    |                n/a                |                     Stable                    |                         Stable                         |               Stable               |                Stable                |               Stable               |             Dev            |              Dev             |               Dev              |
+| Drupal core version  |                n/a                |                    Current                    |                         Current                        |               Current              |                Current               |         Previous<br />minor        |           Current          |            Current           |    Latest pre-<br />release    |
+| Static analysis      |           :black_circle:          |                 :white_circle:                |                     :white_circle:                     |           :white_circle:           |            :white_circle:            |           :white_circle:           |       :white_circle:       |        :white_circle:        |         :white_circle:         |
+| Deprecated code scan |           :white_circle:          |                 :black_circle:                |                     :black_circle:                     |           :white_circle:           |            :white_circle:            |           :white_circle:           |       :white_circle:       |        :white_circle:        |         :white_circle:         |
+| Automated tests      |           :white_circle:          |                 :white_circle:                |                     :white_circle:                     |           :black_circle:           |            :black_circle:            |           :black_circle:           |       :black_circle:       |        :black_circle:        |         :black_circle:         |
+| Allow failure        |           :white_circle:          |                 :white_circle:                |                     :white_circle:                     |           :white_circle:           |            :white_circle:            |           :white_circle:           |       :black_circle:       |        :black_circle:        |         :black_circle:         |
 
 See [Configuring Travis CI](getting-started.md#configuring-travis-ci).
 

example/.travis.yml

@@ -1,3 +1,21 @@
+# Example Travis CI configuration.
+#
+# This configuration file will cover ORCA integration for most packages almost
+# without modification. Use as follows:
+#
+# 1. Copy this file to your package root:
+#
+#    $ cp example/.travis.yml ../my_package/.travis.yml
+#
+# 2. Change the values in env.global for your package. No other changes are
+#    strictly necessary for a basic integration.
+#
+# 3. Strip the (now unnecessary) comments:
+#
+#    $ grep -v '^ *#' .travis.yml > .travis.yml
+#
+# For advanced needs,
+# @see https://github.com/acquia/orca/blob/develop/docs/advanced-usage.md
 ---
 language: php
 
@@ -15,13 +33,18 @@ cache:
     - "$TMPDIR/phpstan/cache"
 
 env:
+  # Change the following values for your implementation.
   global:
     # Provide your package's name.
     - ORCA_SUT_NAME=drupal/example
     # Specify the name of the nearest Git version branch, e.g., 1.x or 8.x-1.x.
     # This may be the destination branch of a pull request or the nearest
     # ancestor of a topic branch.
     - ORCA_SUT_BRANCH=8.x-1.x
+    # Specify the version of ORCA to use. Use the master branch for the latest
+    # release, develop for Dev/HEAD, or a tag name (e.g., v1.0.0) for a specific
+    # release.
+    - ORCA_VERSION=master
 
 # Execution time is drastically reduced by splitting the build into multiple
 # concurrent jobs.
@@ -34,22 +57,23 @@ matrix:
     - { name: "Deprecated code scan w/ dependencies", env: ORCA_JOB=DEPRECATED_CODE_SCAN_CONTRIB }
     - { name: "Isolated test w/ recommended package versions", env: ORCA_JOB=ISOLATED_RECOMMENDED }
     - { name: "Integrated test w/ recommended package versions", env: ORCA_JOB=INTEGRATED_RECOMMENDED }
+    - { name: "Previous minor version of Drupal core", env: ORCA_JOB=CORE_PREVIOUS }
     - { name: "Isolated test w/ dev package versions", env: ORCA_JOB=ISOLATED_DEV }
     - { name: "Integrated test w/ dev package versions", env: ORCA_JOB=INTEGRATED_DEV }
-    - { name: "Previous minor version of Drupal core", env: ORCA_JOB=CORE_PREVIOUS }
     - { name: "Next pre-release of Drupal core", env: ORCA_JOB=CORE_NEXT }
+  # For various reasons, some jobs are allowed to fail without failing the whole
+  # build. They should still be watched for advance notice of future problems.
+  # @see https://docs.travis-ci.com/user/customizing-the-build#rows-that-are-allowed-to-fail
   allow_failures:
-    - env: ORCA_JOB=DEPRECATED_CODE_SCAN_SUT
+    # Obviously, issues in third party code should not fail a build.
     - env: ORCA_JOB=DEPRECATED_CODE_SCAN_CONTRIB
+    # Dev jobs are allowed to fail due to their inherent instability.
     - env: ORCA_JOB=ISOLATED_DEV
     - env: ORCA_JOB=INTEGRATED_DEV
-    - env: ORCA_JOB=CORE_NEXT
 
 # Install ORCA and prepare the environment.
 before_install:
-  # Clone the master branch for the latest release, develop for the dev HEAD, or
-  # a tag (e.g., v1.0.0) for a specific release.
-  - git clone --branch master --depth 1 https://github.com/acquia/orca.git ../orca
+  - git clone --branch ${ORCA_VERSION} --depth 1 https://github.com/acquia/orca.git ../orca
   - ../orca/bin/travis/before_install.sh
 
 # Create the test fixture and place the SUT.