-
Notifications
You must be signed in to change notification settings - Fork 17
Version Control & Release Management
The main branch of the repository represents a stable, released, versioned plugin release. Ongoing development will happen in feature branches branched off a develop branch, which is itself branched off main. This pattern is commonly referred to as the Gitflow workflow.
New features should be branched off develop and, once complete, merged back into develop via a Pull Request, using a squash merge in order to keep a clean commit history.
Commits should be small and independent items of work, containing changes limited to a distinct idea. Distinct commits are essential in keeping features separate, pushing specific features forward, or reversing or rolling back code if necessary.
The first line of a commit message is a brief summary of the changeset, describing the expected result of the change or what is done to affect change.
git log --oneline -2
# e7b0e87 Fixes i18n Date/Time Formatting Problem for Pickup Time (#38)
# 7c30b8d Removes Closed Days from Pickup List (#37)This brief summary is always required. It is around 50 characters or less, always stopping at 60 characters. The high visibility of the first line makes it critical to craft something that is as descriptive as possible within space limits.
git commit -m "Fixes Current Day Pickup Times"Separated from the summary by a blank line is the longer description. It is optional and includes more details about the commit and its repercussions for developers. It may include links to the related issue, side effects, other solutions that were considered, or backstory. A longer description may be useful during the merge of a feature branch, for example.
git commit
# Fixes Invalid Pickup Intervals
#
# Fixes #44
# Fixes how the starting interval is set, especially during the middle of the current open/close pickup time.
# Sets end time 1 interval past it in order to have the end close pickup time be inclusive for pickup.
# Changes field title and help text for Pickup Days Ahead to be clear that the number does now represent the number of open days inclusive of the current day.In order to avoid large merge conflicts, merges should occur early and often. Do not wait until a feature is complete to merge main into it. Merging should be done as non-fast-forwards (--no-ff) to ensure a record of the merge exists.
When develop is at a state where it's ready to form a new release, create a new release/<version> branch off of develop. In this branch, you'll bump version numbers, update documentation, and generally prepare your release.
We follow the WordPress Core style of versioning rather than traditional SemVer. This means that a move from version 3.9 to 4.0 is no different from a move from version 3.8 to 3.9. When a PATCH version is released it represents a bug fix, or non-code, only change.
Updating the plugin version uses NPM package versioning along with a Grunt task that will update key plugin code and documentation with a matching version.
npm run version:bump major | minor | patch
Examples of incrementing the plugin version would be:
npm run version:bump patch
npm run version:bump minor
npm run version:bump major
To set a specific version without a PATCH/MINOR/MAJOR you can supply that specific version.
npm run version:bump 4.0.1
This repository contains a CHANGELOG.md file, to help provide an accurate, up-to-date record of changes that make it easy to see – in human-friendly terms – what has changed between releases without having to read through the entire Git history. As a general rule, every merge into the develop branch should contain at least one line in the change log, describing the feature or fix. This changelog is used as the source for the changelog found in the plugin readme.txt, which is also available to users of the WordPress.org plugin repository. Both the CHANGELOG.md and the readme.txt need to be independently updated.
This includes running some checks, updating the GitHub README.md from the WordPress plugin readme.txt, and generating an updated language POT file.
npm run build
Once the release changes are ready commit and push the branch to GitHub. Open up a Pull Request against main and merge the release branch (using a non-fast-forward merge which is the default style of GitHub Pull Request merge) into main for deployment.
Once all code quality checks have completed against main prepare a new GitHub Release using the "Draft a new release" functionality. Include a Tag that matches the version bump that was performed in in the release branch, targeting the main branch. Provide a release title that indicates the version and type of release (i.e. "3.8.5 Maintenance Release", "3.9.0 Feature Release"). The release description should be the same as the Changelog entry for the same release number. When all items have been provided "Publish release".
When a release is published a GitHub Action will be triggered to build a release version of the plugin and deploy it to the WordPress.org Plugin repository via Subversion.
Once the release has been deployed, merge main into develop so that develop includes all of the work that was done in the release branch and is aware of the current state of main.
Credits: Much of these instructions were written using the 10up Version Control Best Practices as a baseline.