README

This repo is a boilerplate for doing quick localdev environments managed with composer and docker. By default it will create images to install wordpress/mysql. Webpack is used to bundle and manage assets.

git flow

We use git flow. Git flow encourages a branching git strategy with several types of branches

master (for production)
develop (pre-production)
feature/* (new features)
hotfix/* (bug fixes)
release/* (tagged releases merging into master)

You can install git flow here

Typical development workflow starting

create a new project using composer
- git clone git@bitbucket.org:ucomm/wp-plugin-project-boilerplate.git <new-plugin-name>
- change the name and description of the project in the composer.json file. The name is especially important because it is the name that will be used to require this project using composer.
git flow init -d
create a new bitbucket repo under the ucomm team account
git flow feature start {feature_name} this starts a new branch
work on stuff...
git flow feature finish {feature_name} this merges the branch into develop
test the develop branch and share it with others for approval

See below for instructions on creating hooks for jenkins and bitbucket pipelines for automatic deployment/package management

Creating releases

Tags must follow the semver system. Follow these steps to complete a release

on the develop branch
- check git tag for the most recent version number
- bump the version number in ./{plugin-name}.php
- add changelog notes to ./changelog.md
commit these changes (usually with something like git -m 'version bump [skip ci]')

follow the process below to create a new tagged release.

$ git flow release start {new_tag}
$ git flow release finish {new_tag}
$ # in the first screen add new info or just save the commit message as is
$ # in the second screen type in the same tag you just used and save.
$ git push --tags && git push origin master
$ git checkout develop

Usage

Getting started

This project is intended to get development started quickly. As you develop your individual project, please update this readme with project specific details. If you want, you can use parcel, vite, or some other build system instead of webpack. That's completely fine, you simply need to add documentation. Also please update the changelog with notes about new versions.

NB - If you anticipate needing to use a plugin which needs access to the vendor directory, map it as follow. In docker-compose.yml, find the web image and under volumes write - ./vendor:/var/www/html/content/plugins/{plugin_name}/vendor. This gives both the current theme and plugin the vendor folder.

To get a project running.

$ composer install # <- first time only
$ nvm use
$ npm install
$ docker-compose up # <- in one terminal
$ npm run dev # <- in another terminal

UComm composer dependencies

To add any of our projects (plugins, themes, etc...) they need to be added as dependencies. To do that, you will need to first add them to the composer.json "repositories" array. To do that, add the vcs type key and the git URL of the project. For example:

{
   "repositories": [
    {
      "type": "composer",
      "url": "https://wpackagist.org"
    },
    {
      "type": "vcs",
      "url": "git@bitbucket.org:ucomm/uconn-health-clinical.git"
    }
    // other dependencies
  ] 
}

These can then be required with composer require ucomm/project-name.

Local asset development

This boilerplate comes with a minimal webpack config file to bundle JS and CSS assets. You will likely need to adjust the config as you go. That's ok, just (as usual) comment the code if there's anything really unique.

Viewing a project.

This project will be available at localhost.

Accessing containers

To access a particular docker container, find the container name and then enter an interactive terminal.

$ docker ps # to get the container name
$ docker exec -it container_name bash

Debugging Wordpress

Wordpress debug logs can be found inside the web container at /etc/httpd/logs/error_log

Bitbucket

Creating releases

Assuming you're using git flow, tag the release with the command git flow release start {version_number}. Tags must follow the semver system. Follow these steps to complete a release

$ git tag # check the current tags/versions on the project
$ git flow release start {new_tag}
$ git flow release finish {new_tag}
$ # in the first screen add new info or just save the commit message as is
$ # in the second screen type in the same tag you just used and save.
$ git push --tags && git push origin master
$ git checkout develop

ITS Packeton

Some plugins should go to ITS as well as our servers and bitbucket. To aid in this, they have set up a private composer repository. They use this repo to update composer dependencies for Aurora. To add a plugin to this repo, you will need to first go to packeton and add it as follows:

log in
click "Submit"
select repo type -> "Custom (JSON)"
add the name of the plugin from the composer.json file
under custom versions, add a starter version of 0.0.0
upload a dummy zip file (it can be empty)
click "check" then "submit"

Then, in bitbucket, you'll need to add the https://ci.webdev-utils.its.uconn.edu/bitbucket-hook/ webhook to the repository.

Finally, in the Jenkinsfile, you'll need to add environment variables for

a PACKETON_GIT_URL set to the git url of the project
the PACKAGE_NAME set to the name of the package from the composer.json file
the API_TOKEN set from jenkins as credentials('packeton-credentials')

Consult the uconn-today-plugin repo as a good example

Jenkins

Multibranch Pipelines

Use of multibranch pipelines via a Jenkinsfile is strongly recommended. The Jenkinsfile in this project will get you started. To integrate the project with Jenkins, ensure you've done the following steps:

Add a webhook to the repository to trigger a build on push
Add a multibranch pipeline project to the appropriate directory in Jenkins (e.g. comm0 and staging0 management/plugins)
In the project, complete the following configuration
- git project repository for the project
- use the jenkins ssh credentials
- Behaviors should be set to "discover branches" and "discover tags"
- set build strategies to use names for develop, main and feature/* and tags with a sensible ignore pattern
- check the box for "build when a change is pushed to Bitbucket"
- check the box for "discard old items" with a max of 5

Build/Push/Update Strategy

As of 2025-06 the build strategy takes advantage of wp cli to update plugins. This is preferred over rsync because it is non-destructive if it's misconfigured. Builds take the following form

jenkins
- checks out the repo
- creates js/css/php assets as needed using nvm/npm as needed and composer as needed
- an archive zip file is created in plugin-dist from the zip-includes.txt manifest. make sure to update this file as you add new parts to the plugin
- a local version is determined for pushes to bitbucket or packeton
- the zip file is sent to a target server based on the branch. it should always be sent to /home/deploy/ucomm-plugins which is a central repository of local zip files that are pushed by jenkins.
- the plugin is updated using wp cli
- the plugin zip is sent to bitbucket as an archive
- cleanup occurs

Push Strategy for Production

When pushing to production, there is a dry run step. You will need to manually check the output of the dry run and confirm it. Then, you'll need to re-run the pipeline with the dry run flag set to false.

Using wp-project-boilerplate for a plugin

It would be a good idea to keep UComm/WordPress dependencies in require-dev, and only keep functional dependencies in "require". That way, your package will export with only the required files for your plugin/theme to function, and not include a full WP install. See the Castor plugin for an example that uses both.

ucomm / wp-plugin-project-boilerplate

Maintainers

Details

README

git flow

Typical development workflow starting

Creating releases

Usage

Getting started

To get a project running.

UComm composer dependencies

Local asset development

Viewing a project.

Accessing containers

Debugging Wordpress

Bitbucket

Creating releases

ITS Packeton

Jenkins

Multibranch Pipelines

Build/Push/Update Strategy

Push Strategy for Production

Using wp-project-boilerplate for a plugin