README.md

Custom GitHub actions

Custom GitHub actions that help to composite GitHub workflows across the repos maintained by the Grow Team.

Actions list

• automerge-released-trunk - Merge trunk to develop after an extension release
• branch-label - Set PR labels according to the branch name
• coverage-report - Add a clover coverage report as a PR comment
• eslint-annotation - Annotate eslint results via eslint formatter
• get-plugin-releases - Get latest releases versions from WordPress or from a plugin.
• get-release-notes - Get release notes via GitHub, infer the next version and tag
• hook-documentation - Generate WordPress hook documentation
• merge-trunk-develop-pr - Create a PR to merge trunk to develop after an extension release
• phpcs-diff - Run PHPCS to the changed lines of code, set error annotations to a pull request
• prepare-extension-release - Create the release branch & PR with checklist
• prepare-mysql - Enable MySQL, handle authentication compatibility
• prepare-node - Set up Node.js with a specific version, load npm cache, install Node dependencies
• prepare-php - Set up PHP with a specific version and tools, load Composer cache, install Composer dependencies
• publish-extension-dev-build - Publish extension development build
• run-qit-annotate - Runs QIT test and annotates the results
• run-qit-extension - Run QIT tests for a given extension
• stylelint-annotation - Annotate stylelint results via stylelint formatter
• update-version-tags - Update version tags

Prerequisites

JavaScript actions

1. Install node with version >= 14
2. Install node modules npm i

PHP actions

1. Install composer with version >= 2
2. Run composer install in the action directory
3. Write tests as needed for changes to the action(s)
4. Run composer test to run the tests, and composer test:coverage to generate an HTML coverage report

Development

Directory structure of source code

/packages/github-actions/     # The root of actions
├── actions/                  # All actions to be exposed in the release build
│   ├── prepare-node/         # Composite action
│   │   ├── action.yml
│   │   └── README.md         # How to use this action
│   ├── update-version-tags/  # JavaScript action
│   │   ├── src/              # Script sources
│   │   │   ├── index.js
│   │   │   └── parse-version.js
│   │   ├── action.yml
│   │   └── README.md
│   └── hook-documentation/   # PHP action
│       ├── src/              # Script sources
│       ├── tests/            # Unit tests for the action
│       ├── coverage/         # Directory containg Code coverage report after `composer test:coverage` is run
│       ├── composer.json     # The necessary file used to identify this as a PHP action
│       └── action.yml        # The action file
├── utils/                    # Sources of the shared files
│   └── do-something.js
├── package.json              # The required dependent packages of the scripts, tests, build, and etc
└── README.md                 # The overall info about this Github actions package

• The src directories of JavaScript actions will be skipped in the release build.
• When adding a new script that needs to be built, add its build script to package.json and make sure it will be called in npm run build.

Create a test build

Create a test build on the given branch and commit it to a separate branch with the -test-build suffix to facilitate testing and development.

1. Go to Workflow GitHub Actions - Create Test Build
2. Manually run the workflow with the target branch.
3. Wait for the triggered workflow run to complete.
4. View the summary of the workflow run to use the test build.
5. Take the branch name add/my-action and action path greet-visitor as an example:
   • After a test build is created, it should be able to test the custom action by woocommerce/grow/greet-visitor@add/my-action-test-build.
   • After the add/my-action branch is deleted, the Workflow GitHub Actions - Delete Test Build will delete the my-action-test-build branch.

Directory structure of release build

/                               # Entry points for the caller repositories
├── prepare-node/
│   ├── action.yml
│   └── README.md
├── update-version-tags/
│   ├── update-version-tags.js  # Built file
│   ├── action.yml
│   └── README.md
└── README.md                   # Document prompts viewers to find the correct source code

The release build will be committed to a standalone point in the git tree via the release workflow, to make these custom GitHub actions have better paths and can be fetched faster.

%%{
  init: {
    "gitGraph": {
      "mainBranchName": "trunk",
      "mainBranchOrder": 2
    },
    "themeVariables": {
      "git0": "#2155CD",
      "git1": "#5D8BF4",
      "git2": "#66B7FF",
      "git3": "#2FA4FF",
      "gitBranchLabel0": "#FFFFFF",
      "gitBranchLabel1": "#FFFFFF",
      "gitBranchLabel2": "#FFFFFF",
      "gitBranchLabel3": "#FFFFFF",
      "tagLabelBorder": "#874356",
      "tagLabelBackground": "#F73D93",
      "tagLabelColor": "#FFFFFF",
      "commitLabelBackground": "#DFDFDE",
      "gitInv0": "#2155CD"
    }
  }
}%%

gitGraph
  commit
  commit
  branch add/action-feature order: 3
  commit
  commit
  checkout trunk
  merge add/action-feature
  branch release/actions order: 1
  commit id: "Changelog"
  commit id: "Bump version"
  branch tmp/release-build order: 0
  commit id: "Release build" type: HIGHLIGHT tag: "actions-v1.2.3"
  checkout trunk
  merge release/actions

Loading

Release

Official release process

1. 🧑‍💻 Create the specific branch release/actions onto the target revision on trunk branch.
2. When the branch release/actions is created, will continue to commit the release content to release/actions branch.
   • Workflow GitHub Actions - Prepare New Release
   • Prepend changelog to CHANGELOG.md.
   • Update versions to package.json and package-lock.json.
   • Creates a release PR from release/actions branch with trunk as the base branch.
3. 🧑‍💻 Check if the new changelog content and updated version are correct.
   • For a patch version like fixing bugs, increases the Z number. For example, actions-v1.4.8.
   • For a minor version like adding new features, increases the Y number and reset the Z to 0. For example, actions-v1.5.0.
   • For a major version like having incompatible changes, increases the X number and reset the Y and Z to 0. For example, actions-v2.0.0.
   • If something needs to be revised, append the changes in the release PR.
4. 🧑‍💻 If it's all good, approve the release PR to proceed with the next workflow.
5. Once the release PR is approved, a workflow will create a new release with a new version tag.
   • Workflow GitHub Actions - Create Release
6. After publishing the new release, a workflow will continue to create and commit the release build. And then update the references of the corresponding major and minor version tags onto the new release.
   • Workflow GitHub Actions - Release
   • When the new release version is actions-v1.4.8, it should update the references of actions-v1 and actions-v1.4 onto actions-v1.4.8.
   • When the new release version is actions-v1.5.0, it should update the reference of actions-v1 and create actions-v1.5 tag onto actions-v1.5.0.
   • When the new release version is actions-v2.0.0, it should create actions-v2 and actions-v2.0 tags onto actions-v2.0.0.
7. 🧑‍💻 Check if both release workflows are run successfully.
8. 🧑‍💻 Merge the release PR.

Testing the release process

💡 To create a test build based on a branch, please refer to the Create a test build section.

1. Create a new release with a prerelease version tag. For example actions-vX.Y.Z-pre.
2. Check if the "GitHub Actions - Release" workflow is run successfully.
3. Delete the testing releases and tags once they are no longer in use.

Made with 💜 by Woo.
We're hiring! Come work with us!