Web Publish 3

Advanced

Customizing the Queen's CMS Platform

Getting Started with Advanced

Prerequisites

To make use of the Advanced version of WebPublish 3.0, users will need significant expertise in HTML, CSS, PHP, Git, Drupal, Composer, and Drush.  Users should also have a very basic understanding of Docker, Linux, Apache, and Azure DevOps CI/CD Pipelines. Advanced Web Publish 3.0 should only be used for units that have their own dedicated web developer / team and in instances where they require custom modules and themes that can't be fulfilled using alternative methods. 

Overview

Web Publish 3 Advanced is essentially just a recipe, the same recipe ITS uses to build the WebPublish 3 Basic and Custom.  The recipe is forked into your own Azure DevOps Repository and connected to Azure build and deployment resources.

Provisioning and Initial Training

After requesting an account and receiving approval from the Website Governance Committee, your site will be provisioned by the ITS WebPublish team and a training session will be arranged.  The initial training will cover an overview of DevOps Repo and Pipeline functionality as provisioned for Web Publish 3.0 Advanced.

Initial Setup

  1. Login to Azure DevOps
  2. Click on your project
  3. Navigate to Repos
  4. Click Clone button
  5. Click the Generate Git Credentials button
  6. Save the provided personal access token
  7. Clone the repo to your workstation for local development

Customizing WP3

You can add themes, modules, and profiles to your fork of the repo. To customize your instance of Advanced WebPublish 3.0, you can run composer commands from your workstation and commit the resulting changes in the composer.json and composer.lock files to the repo, or you may create your own Azure Pipeline to handle the customization process in an automated way. View a sample customization pipeline

Admin Scripts

Review the Admin folder in the repository to see the available admin scripts.  More documentation will be added to this section later but for now you can review the code in the repo to follow how the scripts work and what inputs are needed.  You may add additional admin scripts to your own repo fork.

Upstream Update Process

When new updates are available from the Public WebPublish3 repository, use this process to integrate them into your WP3 fork.

De-customize Prior to Pull Request

Prior to running a pull request from the Public WebPublish3 repository to update your fork, you must first restore your composer.json and composer.lock files back to a clean un-customized state or the pull request merge will fail. We recommend that you create another Azure Pipeline to handle the de-customization process. View a sample de-customization pipeline.  Ensure your de-customization process includes "[skip ci]" in the commit message to prevent the build and release pipelines from triggering automatically.

Pull Request

  1. Navigate to Repos
  2. Click Pull requests
  3. Click New pull request
  4. Ensure that "Public WebPublish 3" repo is on the left and your project's repo is on the right
  5. Review the files and commits, fill out the title and description, click create.
  6. If no merge conflicts exist, click complete. Ensure that your commit message contains either "Merged PR" or "[skip ci]" to ensure the build and release pipelines are not triggered automatically.
  7. Run your customization pipeline or re-add your modules, themes, and profiles using composer on your workstation.

Theme and Profile Forks

Along with the main Public WebPublish3 repo, you will also be provided access to the basic and custom WP3 themes and profiles.  You can fork these repos into your own project to create unit specific versions.  You will also be able to use the pull requests to merge in changes the primary versions of these forked repos.
  

Deployment

Deployment to the dev server happens automatically on every repo commit unless you add "[skip ci]" to your commit message. To deploy to prev or prod:

  1. Navigate to Pipelines => Releases
  2. Click the prev or prod stage button next to the release
  3. Click deploy
  4. Click deploy