install

#!/usr/bin/env bash
#
# Installs an extension or skin (and its dependencies) into an existing MediaWiki core.
# Skips core installation (assumes ./fresh_install has already installed core).
# Run ./shellto afterwards to open a shell with MediaWiki running.
#
# Usage: ./install extensions/Echo
#        ./install skins/MinervaNeue
#        ENVIRONMENT=0 ./install extensions/Echo
#        QUIBBLE_DEPS="" ./install extensions/Echo                    # no dependencies
#        QUIBBLE_DEPS="EventLogging" ./install extensions/Echo        # only specific dependencies
#        DRY_RUN=1 ./install extensions/Echo                          # pass --dry-run to Quibble (no real install)
#        RESOLVE_REQUIRES=0 ./install extensions/Echo                 # install only QUIBBLE_DEPS; do not auto-resolve transitive requires
#        BRANCH=REL1_44 ./install extensions/Echo                     # install and check out a branch (default: leave Quibble's detached HEAD)
#        GERRIT_PATCHES="refs/changes/20/1306020/1" ./install extensions/Echo  # fetch and check out a Gerrit patch for the component
#
# QUIBBLE_DEPS: Override which dependencies to install (space-separated). When set, replaces
#               the dependencies from zuul/dependencies.yaml. Set to empty string for no
#               dependencies.
#
# RESOLVE_REQUIRES: Default 1. When 1, passes --resolve-requires to Quibble so it resolves
#                   and installs transitive dependencies from each repo's extension.json/skin.json
#                   "requires" field. Set to 0 to install exactly the deps listed in QUIBBLE_DEPS
#                   (used by find_dependencies_minimal_* scripts for honest minimization).
#
# BRANCH: When set, passes --branch to Quibble (which branch to clone/install for the component
#         and its dependencies) and re-attaches HEAD to it afterwards, so the repos are on a
#         named branch instead of Quibble's detached HEAD. Unset (default): leave the detached
#         HEAD as Quibble produces it.
#
# GERRIT_PATCHES: When set, after the install, fetch the given Gerrit patch and check it out in the
#         named component (e.g. src/extensions/Echo). Takes a single change ref that must belong to
#         that component (e.g. "refs/changes/20/1306020/1"). Applied after install, so a patch that
#         only changes code, tests, or in-tree config takes effect immediately; a patch that adds
#         third-party composer/npm dependencies needs a re-install.
#
# See: https://www.mediawiki.org/wiki/Selenium/How-to/Run_tests_targeting_Quibble#Install_MediaWiki_Core_and_an_Extension
#
set -euo pipefail # exit on error, undefined vars, or pipe failures

# Show usage if no argument provided
if [ $# -eq 0 ]; then # $# is the number of arguments
  echo "Usage: ./install extensions/EXTENSION or ./install skins/SKIN"
  exit 1
fi

# Build paths from the component argument (e.g. "extensions/Echo")
component="$1"
repo="mediawiki/${component}"       # e.g. "mediawiki/extensions/Echo"

. "$(dirname "$0")"/lib/setup # source shared setup (docker checks, shared vars, output capture, trace into the log)
. "$(dirname "$0")"/lib/clone_or_fetch # provides clone_or_fetch function
. "$(dirname "$0")"/lib/print_quibble_command # provides print_quibble_command function
. "$(dirname "$0")"/lib/checkout_branch # provides checkout_branch function (BRANCH support)
. "$(dirname "$0")"/lib/apply_gerrit_patch # provides apply_gerrit_patch function (GERRIT_PATCHES support)

# Clone or fetch bare repos for the extension/skin and integration/config
clone_or_fetch "$repo"              # e.g. "mediawiki/extensions/Echo"
clone_or_fetch "integration/config" # needed by ./list_dependencies
# Ensure integration/config working copy exists (needed by ./list_dependencies)
. "$(dirname "$0")"/lib/ensure_config

# Resolve dependency repos and clone bare repos as needed.
# Sets the deps array with repo paths (e.g. "mediawiki/extensions/Echo").
. "$(dirname "$0")"/lib/resolve_deps

# Build the docker command in an array so we can both print and execute it.
# ${QUIBBLE_DOCKER_FLAGS[@]+"..."}: -i (default) or empty (background worker); ${arr[@]+"..."} guards the empty case for bash 3.2 (set by lib/setup)
# --rm: remove container on exit
# --entrypoint=quibble-with-supervisord: use Quibble's supervisord entrypoint
# "${QUIBBLE_VOLUMES[@]}": mount shared volumes (cache, log, ref, src)
# -e ZUUL_PROJECT: tell Quibble which extension/skin is the main project
# "${QUIBBLE_DRY_RUN[@]}": --dry-run when DRY_RUN=1 (set by lib/setup); empty otherwise
# "${QUIBBLE_RESOLVE_REQUIRES[@]}": --resolve-requires by default; empty when RESOLVE_REQUIRES=0 (set by lib/setup)
# "${QUIBBLE_BRANCH[@]}": --branch <branch> when BRANCH is set (set by lib/setup); empty otherwise
# --command true: install only, don't run tests
# ${deps[@]+"..."}: list of dependency repos to clone; ${arr[@]+"..."} is safe for empty arrays in bash 3.2
cmd=(
  docker run ${QUIBBLE_DOCKER_FLAGS[@]+"${QUIBBLE_DOCKER_FLAGS[@]}"} --rm
  --entrypoint=quibble-with-supervisord
  "${QUIBBLE_VOLUMES[@]}"
  -e ZUUL_PROJECT="${repo}"
  "$QUIBBLE_IMAGE"
  ${QUIBBLE_DRY_RUN[@]+"${QUIBBLE_DRY_RUN[@]}"}
  ${QUIBBLE_RESOLVE_REQUIRES[@]+"${QUIBBLE_RESOLVE_REQUIRES[@]}"}
  ${QUIBBLE_BRANCH[@]+"${QUIBBLE_BRANCH[@]}"}
  --command true
  ${deps[@]+"${deps[@]}"}
)
# Pretty-print the command (one option per line, framed by a '#' banner) so it stands
# out in busy logs. It lands wherever the output is captured (the script's log file,
# or a batch parent's per-step log).
print_quibble_command "${cmd[@]}"
"${cmd[@]}"

# When BRANCH is set, re-attach HEAD to that branch (Quibble leaves the cloned repos detached).
# No-op when BRANCH is unset or DRY_RUN=1.
checkout_branch

# When GERRIT_PATCHES is set, fetch and check out the patch in the component (src/$component).
# The patch belongs to the component, so the target is its working copy and project ($repo, e.g.
# mediawiki/extensions/Echo). No-op when GERRIT_PATCHES is unset or DRY_RUN=1.
apply_gerrit_patch "/workspace/src/$component" "$repo"