Repository: 10up/actions-wordpress Branch: stable Commit: 6e0878cd9f5a Files: 17 Total size: 38.9 KB Directory structure: gitextract_xh05tigb/ ├── .github/ │ ├── CODEOWNERS │ ├── ISSUE_TEMPLATE/ │ │ ├── 1-hookdoc-generator-issue.md │ │ ├── 2-new-action.md │ │ ├── 3-ask-a-question.md │ │ └── config.yml │ └── workflows/ │ └── close-stale-issues.yml ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── dotorg-plugin-asset-update/ │ ├── Dockerfile │ ├── README.md │ └── entrypoint.sh ├── dotorg-plugin-deploy/ │ ├── Dockerfile │ ├── README.md │ └── entrypoint.sh ├── using-markdown-in-action-summary.md └── wp-hooks-documentor-workflow.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/CODEOWNERS ================================================ # These owners will be the default owners for everything in the repo. Unless a later match takes precedence, @10up/open-source-practice, as primary maintainers will be requested for review when someone opens a Pull Request. * @10up/open-source-practice # GitHub and WordPress.org specifics /.github/ @jeffpaul LICENSE @jeffpaul ================================================ FILE: .github/ISSUE_TEMPLATE/1-hookdoc-generator-issue.md ================================================ --- name: "\U0001F41B Issue with hook documentation generator" about: Create a report to help us improve title: '' labels: bug assignees: '' --- **Describe the bug** **Steps to Reproduce** 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error **Expected behavior** **Additional context** ================================================ FILE: .github/ISSUE_TEMPLATE/2-new-action.md ================================================ --- name: "\U0001F680 New Action" about: Suggest an idea for a new GitHub Action title: '' labels: enhancement assignees: '' --- **Is your enhancement related to a problem? Please describe.** **Describe the solution you'd like** **Designs** **Describe alternatives you've considered** **Additional context** ================================================ FILE: .github/ISSUE_TEMPLATE/3-ask-a-question.md ================================================ --- name: "❓ Need help?" about: Ask us a question, we're here to help! title: '' labels: question assignees: '' --- **Describe your question** ================================================ FILE: .github/ISSUE_TEMPLATE/config.yml ================================================ blank_issues_enabled: false contact_links: - name: Deploying a plugin to the WordPress.org repository url: https://github.com/10up/action-wordpress-plugin-deploy/issues/new/choose about: Please open issues related to our WordPress.org deploy action here. - name: Deploying plugin asset/readme updates to the WordPress.org repository url: https://github.com/10up/action-wordpress-plugin-asset-update/issues/new/choose about: Please open issues related to our WordPress.org readme/asset updater action here. ================================================ FILE: .github/workflows/close-stale-issues.yml ================================================ name: 'Close stale issues' # **What it does**: Closes issues where the original author doesn't respond to a request for information. # **Why we have it**: To remove the need for maintainers to remember to check back on issues periodically to see if contributors have responded. on: schedule: # Schedule for every day at 1:30am UTC - cron: '30 1 * * *' permissions: issues: write jobs: stale: runs-on: ubuntu-latest steps: - uses: actions/stale@v9 with: days-before-stale: 7 days-before-close: 7 stale-issue-message: > It has been 7 days since more information was requested from you in this issue and we have not heard back. This issue is now marked as stale and will be closed in 7 days, but if you have more information to add then please comment and the issue will stay open. close-issue-message: > This issue has been automatically closed because there has been no response to our request for more information. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. See [this blog post on bug reports and the importance of repro steps](https://www.lee-dohm.com/2015/01/04/writing-good-bug-reports/) for more information about the kind of information that may be helpful. stale-issue-label: 'stale' close-issue-reason: 'not_planned' any-of-labels: 'needs:feedback' remove-stale-when-updated: true ================================================ FILE: CONTRIBUTING.md ================================================ # Contributing and Maintaining First, thank you for taking the time to contribute! The following is a set of guidelines for contributors as well as information and instructions around our maintenance process. The two are closely tied together in terms of how we all work together and set expectations, so while you may not need to know everything in here to submit an issue or pull request, it's best to keep them in the same document. ## Ways to contribute Contributing isn't just writing code - it's anything that improves the project. All contributions for our GitHub Actions for WordPress are managed right here on GitHub. Here are some ways you can help: ### Reporting bugs and requesting enhancements If you're running into a problem with an action or would like to see it do something more, please open an issue in the repository for that specific action. ### Suggesting new actions Ideas for future actions can be found in [issues](https://github.com/10up/actions-wordpress/issues). ### Pull requests Pull requests will likely be uncommon but are welcomed as necessary! ## Workflow This repository currently only actively uses the `stable` branch as it is meant to serve as a documentation source. The Action subdirectories in this repository are kept for historical reasons. ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2019 Helen Hou-Sandi Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # GitHub Actions for WordPress! > Here is a collection of GitHub Actions and workflows to help with common needs for WordPress development. Specific documentation for each Action is in its respective respository, and other example workflows leveraging existing Actions can be found in this repository. Ideas for future Actions can be found in [issues](https://github.com/10up/actions-wordpress/issues). [![Support Level](https://img.shields.io/badge/support-active-green.svg)](#support-level) [![MIT License](https://img.shields.io/github/license/10up/actions-wordpress.svg)](https://github.com/10up/actions-wordpress/blob/master/LICENSE) [More information about GitHub Actions](https://github.com/features/actions/) ## Ready to use The following GitHub Actions are published, available to use, and actively supported by 10up. ### [Deploying a plugin to the WordPress.org repository](https://github.com/10up/action-wordpress-plugin-deploy) [![Support Level](https://img.shields.io/badge/support-active-green.svg)](https://github.com/10up/action-wordpress-plugin-deploy/blob/develop/README.md#support-level) [![Release Version](https://img.shields.io/github/release/10up/action-wordpress-plugin-deploy.svg)](https://github.com/10up/action-wordpress-plugin-deploy/releases/latest) [![MIT License](https://img.shields.io/github/license/10up/action-wordpress-plugin-deploy.svg)](https://github.com/10up/action-wordpress-plugin-deploy/blob/develop/LICENSE) Whenever you tag a new version of your plugin on GitHub, your changes will be committed to both `trunk` and the appropriate `tags` subfolder in your WordPress.org plugin repository. ### [WordPress.org Plugin Build Zip Archive](https://github.com/10up/action-wordpress-plugin-build-zip) [![Support Level](https://img.shields.io/badge/support-active-green.svg)](#support-level) [![Release Version](https://img.shields.io/github/release/10up/action-wordpress-plugin-build-zip.svg)](https://github.com/10up/action-wordpress-plugin-build-zip/releases/latest) [![MIT License](https://img.shields.io/github/license/10up/action-wordpress-plugin-build-zip.svg)](https://github.com/10up/action-wordpress-plugin-build-zip/blob/develop/LICENSE) This Action will build a zip archive of your WordPress plugin and attach that archive as an artifact, allowing you to download and test prior to deploying any changes to WordPress.org. This gives you the peace of mind knowing you've tested exactly what will be deployed. Recommended to be used in conjunction with our [WordPress.org Plugin Deploy Action](https://github.com/10up/action-wordpress-plugin-deploy) as both Actions create the archive in the same way. An ideal workflow is to run this Action first and test the zip archive it provides. Once testing passes, then run our deploy Action to push changes to WordPress.org. ### [Deploying plugin asset/readme updates to the WordPress.org repository](https://github.com/10up/action-wordpress-plugin-asset-update) [![Support Level](https://img.shields.io/badge/support-active-green.svg)](https://github.com/10up/action-wordpress-plugin-asset-update/blob/develop/README.md#support-level) [![Release Version](https://img.shields.io/github/release/10up/action-wordpress-plugin-asset-update.svg)](https://github.com/10up/action-wordpress-plugin-asset-update/releases/latest) [![MIT License](https://img.shields.io/github/license/10up/action-wordpress-plugin-asset-update.svg)](https://github.com/10up/action-wordpress-plugin-asset-update/blob/develop/LICENSE) If you push to your specified branch and it only contains changes to the WordPress.org assets directory (defaults to `/.wordpress-org`) or `readme.txt`, deploy those changes to the WordPress.org plugin repository. This is useful for being able to update things like screenshots or the `Tested up to` version in between tagged releases. ### [PHP linting without additional codebase dependencies](https://github.com/10up/wpcs-action) [![Support Level](https://img.shields.io/badge/support-active-green.svg)](https://github.com/10up/wpcs-action/blob/develop/README.md#support-level) [![Release Version](https://img.shields.io/github/release/10up/wpcs-action.svg)](https://github.com/10up/wpcs-action/releases/latest) [![MIT License](https://img.shields.io/github/license/10up/wpcs-action.svg)](https://github.com/10up/wpcs-action/blob/develop/LICENSE) This action will run PHPCS ([PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)) against [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards) and show warnings and errors as annotations in your PRs without adding PHPCS as a dependency or a PHP CodeSniffer config. ### [Deploying WordPress sites to Pantheon](https://github.com/10up/pantheon-wp-deploy-action) [![Support Level](https://img.shields.io/badge/support-active-green.svg)](#support-level) [![Release Version](https://img.shields.io/github/release/10up/pantheon-wp-deploy-action.svg)](https://github.com/10up/pantheon-wp-deploy-action/releases/latest) [![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://github.com/10up/pantheon-wp-deploy-action/blob/trunk/LICENSE) [![Automated Tests](https://github.com/10up/pantheon-wp-deploy-action/actions/workflows/test.yml/badge.svg)](https://github.com/10up/pantheon-wp-deploy-action/actions/workflows/test.yml) The code in Pantheon's git main branch is production ready (preprod and production environments only) therefore our preferred deployment workflow for GitHub + Pantheon sites is: - Use Pantheon multidev environments for the project's lower environments (dev, staging, etc.) and create a GitHub branch with the same name as the multidev environment to automatically deploy to them - The GitHub main branch deploys to the Pantheon's `Dev` environment but automatically promotes the code to the Pantheon `Test` environment -- We use the Pantheon's `Test` environment as our preprod environment - Once the changes have been tested we promote the code in the `Test` environment to `Live` ### [WordPress Scanner Action](https://github.com/10up/wp-scanner-action) [![Support Level](https://img.shields.io/badge/support-active-green.svg)](#support-level) [![Release Version](https://img.shields.io/github/release/10up/wp-scanner-action.svg)](https://github.com/10up/wp-scanner-action/releases/latest) [![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/10up/wp-scanner-action/blob/trunk/LICENSE.md) [![Automated Tests](https://github.com/10up/wp-scanner-action/actions/workflows/tests.yml/badge.svg)](https://github.com/10up/wp-scanner-action/actions/workflows/tests.yml) GitHub Action to perform various checks for WordPress sites (Syntax, Virus, known vulnerabilities). This Action leverages our own [WP-CLI Vulnerability Scanner](https://github.com/10up/wpcli-vulnerability-scanner) to perform the known vulnerabilities scanning of WordPress plugins and themes. WP-CLI Vulnerability Scanner works with [WPScan](https://wpscan.com), [Patchstack](https://patchstack.com/) and [Wordfence Intelligence](https://www.wordfence.com/threat-intel/) to check reported vulnerabilities; you can choose any one of these three to use. ***Note**: Authentication is optional for the Wordfence Intelligence Vulnerability API.* ### [Automating repository operations](https://github.com/10up/action-repo-automator) [![Support Level](https://img.shields.io/badge/support-beta-blueviolet.svg)](#support-level) [![Release Version](https://img.shields.io/github/release/10up/action-repo-automator.svg)](https://github.com/10up/action-repo-automator/releases/latest) [![License](https://img.shields.io/github/license/10up/action-repo-automator.svg)](https://github.com/10up/action-repo-automator/blob/develop/LICENSE.md) [![CodeQL](https://github.com/10up/action-repo-automator/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/10up/action-repo-automator/actions/workflows/codeql-analysis.yml) This action automates some common repository operations, such as validating PR description, adding labels, auto-assigning issues, auto-requesting reviews on PRs, adding milestones, and many more. - **Validate PR description:** It validates PR description to make sure it contains description of the change, changelog and credits. Also, you can set custom comment message for PR author to inform them about PR description requirements. - **Add Labels:** It helps with adding label to PR when PR validation pass or fail. - **Auto-assign Issues:** This feature helps to automatically assign issue with PR assignee when a linked PR is merged. - **Auto-assign PR:** It helps with assigning PR to the author. - **Auto request review:** It helps with request review from the team or GitHub user given in the configuration. - **Add Milestone:** Automatically adds a Milestone to PRs. If the PR is connected to an issue with a milestone, the same milestone will be added to the PR. Otherwise, the next milestone from the available milestones will be assigned, sorted using version comparison. - **Auto-label merge conflicts:** Automatically adds a label to PRs with merge conflicts, and once a conflict is resolved, the label is automatically removed. - **Auto-comment merge conflicts:** Automatically adds a comment to PRs with merge conflicts to notify the PR author, and once a conflict is resolved, the comment is automatically removed. - **Auto-Sync PR branch:** Automatically keeps the pull request branch up to date with the base branch. - **Welcome first-time contributors:** Greet first-time contributors with a warm welcome message on their first issue or PR to the project. - **Auto-comment on new Issues/PRs:** Automatically adds a comment to newly opened issues and PRs. This can be used to request users to provide as much context as possible or share links to your contributing guidelines, or anything else that suits your use case. ### [Publishing generated hook documentation to GitHub Pages](wp-hooks-documentor-workflow.md) You can use this workflow to automatically generate a documentation for your WordPress plugin hooks (actions and filters) using the [WP Hooks Documentor](https://github.com/10up/wp-hooks-documentor) and publish them to GitHub Pages. For an example of the output, see the [Distributor hook docs](https://10up.github.io/distributor/). ### Validating project dependency licensing If you publish projects that adhere to a certain license (e.g. GPLv2), then you will want to ensure any dependencies within your project adhere to a compatible license. We've crafted a [GitHub Action workflow](https://github.com/10up/insert-special-characters/blob/develop/.github/workflows/dependency-review.yml) and [GPL-Compatible License Policy file](https://github.com/10up/.github/blob/trunk/.github/dependency-review-config.yml) that can be leveraged to ensure your projects are GPL-compatible. Additional license policy files could be developed to ensure other licensing are valid (e.g. a MIT-Compatible License Policy file). ### [Using markdown content in GitHub Actions summary](using-markdown-in-action-summary.md) In May 2022, GitHub introduced the [markdown support](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/) for the GitHub Actions summaries. This feature can help improve the developer experience by generating more useful reports to action summaries. ## Planned * Building a production-ready version into a `stable` branch or other location of choice. ## Contributing Want to help? Check out our [contributing guidelines](CONTRIBUTING.md) to get started. ## Support Level **Active:** 10up is actively working on this, and we expect to continue work for the foreseeable future including keeping tested up to the most recent version of WordPress. Bug reports, feature requests, questions, and pull requests are welcome. ## Like what you see? Work with the 10up WordPress Practice at Fueled ================================================ FILE: dotorg-plugin-asset-update/Dockerfile ================================================ FROM debian:stable-slim LABEL "com.github.actions.name"="WordPress Plugin Readme Update" LABEL "com.github.actions.description"="Deploy readme updates to the WordPress Plugin Repository" LABEL "com.github.actions.icon"="upload-cloud" LABEL "com.github.actions.color"="blue" LABEL maintainer="Helen Hou-Sandí " LABEL version="1.0.0" LABEL repository="http://github.com/helen/actions-wordpress" RUN apt-get update \ && apt-get install -y subversion rsync git \ && apt-get clean -y \ && rm -rf /var/lib/apt/lists/* \ && git config --global user.email "10upbot+github@10up.com" \ && git config --global user.name "10upbot on GitHub" COPY entrypoint.sh /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"] ================================================ FILE: dotorg-plugin-asset-update/README.md ================================================ # WordPress.org Plugin Assets Update ## Moved to https://github.com/10up/action-wordpress-plugin-asset-update The Action will continue to work as-is in your workflow files; however, we recommend migrating to the new repo for future updates. ================================================ FILE: dotorg-plugin-asset-update/entrypoint.sh ================================================ #!/bin/bash # Note that this does not use pipefail because if the grep later # doesn't match I want to be able to show an error first set -eo # Ensure SVN username and password are set # IMPORTANT: while secrets are encrypted and not viewable in the GitHub UI, # they are by necessity provided as plaintext in the context of the Action, # so do not echo or use debug mode unless you want your secrets exposed! if [[ -z "$SVN_USERNAME" ]]; then echo "Set the SVN_USERNAME secret" exit 1 fi if [[ -z "$SVN_PASSWORD" ]]; then echo "Set the SVN_PASSWORD secret" exit 1 fi # Allow some ENV variables to be customized if [[ -z "$SLUG" ]]; then SLUG=${GITHUB_REPOSITORY#*/} fi echo "ℹ︎ SLUG is $SLUG" if [[ -z "$ASSETS_DIR" ]]; then ASSETS_DIR=".wordpress-org" fi echo "ℹ︎ ASSETS_DIR is $ASSETS_DIR" SVN_URL="http://plugins.svn.wordpress.org/${SLUG}/" SVN_DIR="/github/svn-${SLUG}" # Checkout just trunk and assets for efficiency # Stable tag will come later, if applicable echo "➤ Checking out .org repository..." svn checkout --depth immediates "$SVN_URL" "$SVN_DIR" cd "$SVN_DIR" svn update --set-depth infinity assets svn update --set-depth infinity trunk echo "➤ Copying files..." cd "$GITHUB_WORKSPACE" # "Export" a cleaned copy to a temp directory TMP_DIR="/github/archivetmp" mkdir "$TMP_DIR" git config --global user.email "10upbot+github@10up.com" git config --global user.name "10upbot on GitHub" # If there's no .gitattributes file, write a default one into place if [[ ! -e "$GITHUB_WORKSPACE/.gitattributes" ]]; then cat > "$GITHUB_WORKSPACE/.gitattributes" <<-EOL /$ASSETS_DIR export-ignore /.gitattributes export-ignore /.gitignore export-ignore /.github export-ignore EOL # Ensure we are in the $GITHUB_WORKSPACE directory, just in case # The .gitattributes file has to be committed to be used # Just don't push it to the origin repo :) git add .gitattributes && git commit -m "Add .gitattributes file" fi # This will exclude everything in the .gitattributes file with the export-ignore flag git archive HEAD | tar x --directory="$TMP_DIR" cd "$SVN_DIR" # Copy from clean copy to /trunk, excluding dotorg assets # The --delete flag will delete anything in destination that no longer exists in source rsync -rc "$TMP_DIR/" trunk/ --delete # Copy dotorg assets to /assets rsync -rc "$GITHUB_WORKSPACE/$ASSETS_DIR/" assets/ --delete echo "➤ Preparing files..." svn status if [[ -z $(svn stat) ]]; then echo "🛑 Nothing to deploy!" exit 78 # Check if there is more than just the readme.txt modified in trunk # The leading whitespace in the pattern is important # so it doesn't match potential readme.txt in subdirectories! elif svn stat trunk | grep -qvi ' trunk/readme.txt$'; then echo "🛑 Other files have been modified; changes not deployed" exit 1 fi # Readme also has to be updated in the .org tag echo "➤ Preparing stable tag..." STABLE_TAG=$(grep -m 1 "^Stable tag:" "$TMP_DIR/readme.txt" | tr -d '\r\n' | awk -F ' ' '{print $NF}') if [ -z "$STABLE_TAG" ]; then echo "ℹ︎ Could not get stable tag from readme.txt"; HAS_STABLE=1 else echo "ℹ︎ STABLE_TAG is $STABLE_TAG" if svn info "^/$SLUG/tags/$STABLE_TAG" > /dev/null 2>&1; then svn update --set-depth infinity "tags/$STABLE_TAG" # Not doing the copying in SVN for the sake of easy history rsync -c "$TMP_DIR/readme.txt" "tags/$STABLE_TAG/" else echo "ℹ︎ Tag $STABLE_TAG not found" fi fi # Add everything and commit to SVN # The force flag ensures we recurse into subdirectories even if they are already added # Suppress stdout in favor of svn status later for readability svn add . --force > /dev/null # SVN delete all deleted files # Also suppress stdout here svn status | grep '^\!' | sed 's/! *//' | xargs -I% svn rm % > /dev/null # Now show full SVN status svn status echo "➤ Committing files..." svn commit -m "Updating readme/assets from GitHub" --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD" echo "✓ Plugin deployed!" echo "⚠️ Please consider migrating to https://github.com/10up/action-wordpress-plugin-asset-update for the latest version of this Action" ================================================ FILE: dotorg-plugin-deploy/Dockerfile ================================================ FROM debian:stable-slim LABEL "com.github.actions.name"="WordPress Plugin Deploy" LABEL "com.github.actions.description"="Deploy to the WordPress Plugin Repository" LABEL "com.github.actions.icon"="upload-cloud" LABEL "com.github.actions.color"="blue" LABEL maintainer="Helen Hou-Sandí " LABEL version="1.0.0" LABEL repository="http://github.com/helen/actions-wordpress" RUN apt-get update \ && apt-get install -y subversion rsync git \ && apt-get clean -y \ && rm -rf /var/lib/apt/lists/* \ && git config --global user.email "10upbot+github@10up.com" \ && git config --global user.name "10upbot on GitHub" COPY entrypoint.sh /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"] ================================================ FILE: dotorg-plugin-deploy/README.md ================================================ # WordPress.org Plugin Deploy ## Moved to https://github.com/10up/action-wordpress-plugin-deploy The Action will continue to work as-is in your workflow files; however, we recommend migrating to the new repo for future updates. ================================================ FILE: dotorg-plugin-deploy/entrypoint.sh ================================================ #!/bin/bash # Note that this does not use pipefail # because if the grep later doesn't match any deleted files, # which is likely the majority case, # it does not exit with a 0, and I only care about the final exit. set -eo # Ensure SVN username and password are set # IMPORTANT: while secrets are encrypted and not viewable in the GitHub UI, # they are by necessity provided as plaintext in the context of the Action, # so do not echo or use debug mode unless you want your secrets exposed! if [[ -z "$SVN_USERNAME" ]]; then echo "Set the SVN_USERNAME secret" exit 1 fi if [[ -z "$SVN_PASSWORD" ]]; then echo "Set the SVN_PASSWORD secret" exit 1 fi if [[ -z "$GITHUB_TOKEN" ]]; then echo "Set the GITHUB_TOKEN env variable" exit 1 fi # Allow some ENV variables to be customized if [[ -z "$SLUG" ]]; then SLUG=${GITHUB_REPOSITORY#*/} fi echo "ℹ︎ SLUG is $SLUG" # Does it even make sense for VERSION to be editable in a workflow definition? if [[ -z "$VERSION" ]]; then VERSION=${GITHUB_REF#refs/tags/} fi echo "ℹ︎ VERSION is $VERSION" if [[ -z "$ASSETS_DIR" ]]; then ASSETS_DIR=".wordpress-org" fi echo "ℹ︎ ASSETS_DIR is $ASSETS_DIR" SVN_URL="http://plugins.svn.wordpress.org/${SLUG}/" SVN_DIR="/github/svn-${SLUG}" # Checkout just trunk and assets for efficiency # Tagging will be handled on the SVN level echo "➤ Checking out .org repository..." svn checkout --depth immediates "$SVN_URL" "$SVN_DIR" cd "$SVN_DIR" svn update --set-depth infinity assets svn update --set-depth infinity trunk echo "➤ Copying files..." cd "$GITHUB_WORKSPACE" # "Export" a cleaned copy to a temp directory TMP_DIR="/github/archivetmp" mkdir "$TMP_DIR" git config --global user.email "10upbot+github@10up.com" git config --global user.name "10upbot on GitHub" # If there's no .gitattributes file, write a default one into place if [[ ! -e "$GITHUB_WORKSPACE/.gitattributes" ]]; then cat > "$GITHUB_WORKSPACE/.gitattributes" <<-EOL /$ASSETS_DIR export-ignore /.gitattributes export-ignore /.gitignore export-ignore /.github export-ignore EOL # Ensure we are in the $GITHUB_WORKSPACE directory, just in case # The .gitattributes file has to be committed to be used # Just don't push it to the origin repo :) git add .gitattributes && git commit -m "Add .gitattributes file" fi # This will exclude everything in the .gitattributes file with the export-ignore flag git archive HEAD | tar x --directory="$TMP_DIR" cd "$SVN_DIR" # Copy from clean copy to /trunk, excluding dotorg assets # The --delete flag will delete anything in destination that no longer exists in source rsync -rc "$TMP_DIR/" trunk/ --delete # Copy dotorg assets to /assets rsync -rc "$GITHUB_WORKSPACE/$ASSETS_DIR/" assets/ --delete # Add everything and commit to SVN # The force flag ensures we recurse into subdirectories even if they are already added # Suppress stdout in favor of svn status later for readability echo "➤ Preparing files..." svn add . --force > /dev/null # SVN delete all deleted files # Also suppress stdout here svn status | grep '^\!' | sed 's/! *//' | xargs -I% svn rm % > /dev/null # Copy tag locally to make this a single commit echo "➤ Copying tag..." svn cp "trunk" "tags/$VERSION" svn status echo "➤ Committing files..." svn commit -m "Update to version $VERSION from GitHub" --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD" echo "✓ Plugin deployed!" echo "⚠️ Please consider migrating to https://github.com/10up/action-wordpress-plugin-deploy for the latest version of this Action" ================================================ FILE: using-markdown-in-action-summary.md ================================================ # Using Markdown in the action summary In May 2022, GitHub introduced the [markdown support](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/) for the GitHub Actions summaries. This feature can help improve the developer experience by generating more useful reports to action summaries. In practice, we found it's more flexible to integrate with existing workflows than to update the action itself, so the ultimate goal here is creating markdown content from the action report and then outputting the content to the `$GITHUB_STEP_SUMMARY` environment variable. This page shares our results and instruction to integrate the Job summaries feature with our frequently used workflows. ![](https://user-images.githubusercontent.com/5423135/168460231-2192571c-a873-4f23-aedb-5e469216947c.png) ## ESLint For ESLint, we create the markdown summary from the ESLint JSON report. Because there isn't any existing tool to do that, we created [`eslint-json-to-md`](https://github.com/10up/eslint-json-to-md) command to convert the ESLint JSON to markdown content. ### Example workflow ```yml jobs: eslint: name: eslint runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: npm install run: npm install - name: Generate linting report run: npm run lint:js -- --output-file eslint-report.json --format json continue-on-error: true - name: Annotate code linting results uses: ataylorme/eslint-annotate-action@1.2.0 with: repo-token: '${{ secrets.GITHUB_TOKEN }}' report-json: 'eslint-report.json' - name: Update summary run: | npm_config_yes=true npx github:10up/eslint-json-to-md --path ./eslint-report.json --output ./eslint-report.md cat eslint-report.md >> $GITHUB_STEP_SUMMARY if: ${{ failure() }} ``` ### Notes - Because this is a linting workflow, we only generate the markdown report when there are linting issues. - ESLint config can be complex, so we use the project linting script instead of ESLint actions. ## PHPCS Similar to ESLint, PHPCS can generate JSON reports, and we also convert that JSON report to markdown content by using [`phpcs-json-to-md`](https://github.com/10up/phpcs-json-to-md) command. ```yml jobs: phpcs: name: WPCS runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: WPCS check uses: 10up/wpcs-action@stable with: use_local_config: true extra_args: '--report-json=./phpcs-report.json' - name: Update summary run: | npx github:10up/phpcs-json-to-md --path ./phpcs-report.json --output ./phpcs-report.md cat phpcs-report.md >> $GITHUB_STEP_SUMMARY if: ${{ failure() }} ``` ================================================ FILE: wp-hooks-documentor-workflow.md ================================================ # How to generate WordPress plugin hook documentation and deploy it to GitHub Pages You can automatically generate a documentation for your WordPress plugin hooks (actions and filters) using the [WP Hooks Documentor](https://github.com/10up/wp-hooks-documentor)! This workflow uses a npm package combined with GitHub Actions to publish documentation to GitHub Pages, so you don't have to separately worry about keeping your documentation up to date and publicly available. For a live example, see our [Distributor documentation](https://10up.github.io/distributor/) and [ClassifAI documentation](https://10up.github.io/classifai/). ## What you'll need * [Well-documented hooks](#hook-documentation-examples) in your WordPress plugin code * Node.js >= 20.0 and PHP >= 8.3 in your development environment * A build command for the docs, along with `@10up/wp-hooks-documentor` as `devDependencies` in your [`package.json`](#packagejson) * A [`wp-hooks-doc.json`](#wp-hooks-docjson) configuration file in your project root * A [workflow file](#example-workflow-file) in your `.github/workflows` directory The WP Hooks Documentor automatically scans your PHP files for hooks and generates documentation using Docusaurus. You can optionally customize the theme, styling, and content by providing custom templates in your configuration. ## Customization and Theming WP Hooks Documentor uses Docusaurus under the hood, which provides extensive customization options. If the default theme works for your needs, you can skip the configuration entirely! However, you can customize: * **Site branding**: Configure title, tagline and logo through the Docusaurus configuration file. * **Styling**: Customize CSS through Docusaurus theme configuration or by providing custom CSS files. * **Footer**: Configure footer style (light/dark) and copyright text through the configuration file or override the default footer by specifying a `templatesDir` in your configuration. The tool generates a complete Docusaurus site, so you can leverage all of [Docusaurus's theming capabilities](https://docusaurus.io/docs/styling-layout) for advanced customization. ## Installation and Setup ### Installation Install WP Hooks Documentor as a development dependency in your project: ```bash npm install --save-dev @10up/wp-hooks-documentor ``` ### Quick Start 1. Add npm scripts in the package.json ```json "init:docs": "wp-hooks-documentor init", "build:docs": "wp-hooks-documentor generate", ``` 2. Initialize a configuration file in your project root: ```bash npm run init:docs ``` 2. Edit the generated [`wp-hooks-doc.json`](#wp-hooks-docjson) file to match your project settings. 3. Generate documentation: ```bash npm run build:docs ``` ## Testing locally You can generate and preview the documentation locally before deploying: ```bash # Generate documentation npm run build:docs # Navigate to the output directory (default: ./docs) cd ./docs # Start local development server npm run serve ``` The documentation site will be available at `http://localhost:3000` for local preview and testing. ### Hook Documentation Examples WP Hooks Documentor automatically detects WordPress hooks in your PHP code. Here are examples of well-documented hooks: #### Filter Hook Example ```php /** * Filters the taxonomies that should be synced. * * @since 1.0.0 * * @param array $taxonomies Associative array list of taxonomies supported by current post in the format of `$taxonomy => $terms`. * @param WP_Post $post The post object. * * @return array Associative array list of taxonomies supported by current post in the format of `$taxonomy => $terms`. */ $taxonomies = apply_filters( 'dt_syncable_taxonomies', $taxonomies, $post ); ``` #### Action Hook Example ```php /** * Fires the action after a post is pushed via Distributor before remote request validation. * * @since 2.0.0 * * @param array|WP_Error $response The response from the remote request. * @param array $post_body The Post data formatted for the REST API endpoint. * @param string $type_url The Post type api endpoint. * @param int $post_id The Post id. * @param array $args The arguments passed into wp_insert_post. * @param WordPressExternalConnection $this The Distributor connection being pushed to. */ do_action( 'dt_push_external_post', $response, $post_body, $type_url, $post_id, $args, $this ); ``` ## Code examples ### `package.json` ```json { ... "scripts": { ... "docs:init": "wp-hooks-documentor init", "docs:generate": "wp-hooks-documentor generate", }, "devDependencies": { "@10up/wp-hooks-documentor": "^1.0.1" } } ``` ### `wp-hooks-doc.json` Create this configuration file in your project root to customize the documentation generation: ```json { "title": "Plugin Hooks Documentation", "tagline": "Hooks Documentation for the plugin", "url": "https://example.com", "baseUrl": "/", "repoUrl": "https://github.com/username/repo", "organizationName": "username", "projectName": "my-plugin", "input": ".", "ignoreFiles": [ "/tests/", "/vendor/", "/node_modules/" ], "ignoreHooks": [], "outputDir": "./docs", "templatesDir": "./wp-hooks-docs", "footerStyle": "dark", "footerCopyright": "Copyright © 2025 Your Name. Built with WP Hooks Documentor." } ``` ### Example workflow file #### `.github/workflows/build-docs.yml` ```yml name: Build Hook Documentation on: push: branches: - trunk jobs: build-docs: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: Setup proper PHP version uses: shivammathur/setup-php@9e72090525849c5e82e596468b86eb55e9cc5401 # v2.32.0 with: php-version: 8.3 - name: Setup node uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 with: node-version: 20 - name: npm install, and build docs run: | npm install npm run build:docs - name: Deploy to GH Pages uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: './docs/build' ``` ## Questions you may have ### What if I want to build documentation but not deploy it to GitHub Pages? Absolutely! The workflow file is just one example. You can modify it to: - Commit the generated documentation to your repository (e.g., in a `docs/` folder) - Deploy to other hosting platforms like Netlify, Vercel, or AWS S3 - Generate documentation as part of your release process - Use the documentation locally for development purposes ### What hook documentation formats are supported? WP Hooks Documentor works with standard WordPress PHPDoc comments. It automatically detects: - `apply_filters()` calls for filter hooks - `do_action()` calls for action hooks - Hook parameters and descriptions from docblock comments - `@since` version information - Parameter types and descriptions ### How do I exclude certain hooks from documentation? Use the `ignoreHooks` array in your `wp-hooks-doc.json` configuration: ```json { "ignoreHooks": [ "internal_hook_name", ] } ``` ### Can I customize the documentation theme? Yes! WP Hooks Documentor uses Docusaurus, so you can: - Customize colors, fonts, and styling through configuration - Override theme by specifying a `templatesDir` - Add custom CSS and JavaScript - Modify the footer, header, and navigation - Add additional pages and content See the [Docusaurus theming documentation](https://docusaurus.io/docs/styling-layout) for detailed customization options. ### I have another question that's not answered here. Thanks for reading! Please [open an issue](https://github.com/10up/actions-wordpress/issues) with your question or feedback about this guide, or check out the [WP Hooks Documentor repository](https://github.com/10up/wp-hooks-documentor) for more information. ## More Actions for WordPress Developers Do you develop your WordPress plugins on GitHub but still wrestle with SVN to deploy them to WordPress.org? We've got [some Actions](README.md) to help!