[
{
"path": ".github/CODEOWNERS",
"content": "# 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.\n* @10up/open-source-practice\n\n# GitHub and WordPress.org specifics\n/.github/ @jeffpaul\nLICENSE @jeffpaul\n"
},
{
"path": ".github/ISSUE_TEMPLATE/1-hookdoc-generator-issue.md",
"content": "---\nname: \"\\U0001F41B Issue with hook documentation generator\"\nabout: Create a report to help us improve\ntitle: ''\nlabels: bug\nassignees: ''\n\n---\n\n\n\n**Describe the bug**\n\n\n**Steps to Reproduce**\n\n1. Go to '...'\n2. Click on '....'\n3. Scroll down to '....'\n4. See error\n\n**Expected behavior**\n\n\n**Additional context**\n\n"
},
{
"path": ".github/ISSUE_TEMPLATE/2-new-action.md",
"content": "---\nname: \"\\U0001F680 New Action\"\nabout: Suggest an idea for a new GitHub Action\ntitle: ''\nlabels: enhancement\nassignees: ''\n\n---\n\n\n\n**Is your enhancement related to a problem? Please describe.**\n\n\n**Describe the solution you'd like**\n\n\n**Designs**\n\n\n**Describe alternatives you've considered**\n\n\n**Additional context**\n\n"
},
{
"path": ".github/ISSUE_TEMPLATE/3-ask-a-question.md",
"content": "---\nname: \"❓ Need help?\"\nabout: Ask us a question, we're here to help!\ntitle: ''\nlabels: question\nassignees: ''\n\n---\n\n\n\n**Describe your question**\n\n"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"content": "blank_issues_enabled: false\ncontact_links:\n - name: Deploying a plugin to the WordPress.org repository\n url: https://github.com/10up/action-wordpress-plugin-deploy/issues/new/choose\n about: Please open issues related to our WordPress.org deploy action here.\n - name: Deploying plugin asset/readme updates to the WordPress.org repository\n url: https://github.com/10up/action-wordpress-plugin-asset-update/issues/new/choose\n about: Please open issues related to our WordPress.org readme/asset updater action here.\n"
},
{
"path": ".github/workflows/close-stale-issues.yml",
"content": "name: 'Close stale issues'\n\n# **What it does**: Closes issues where the original author doesn't respond to a request for information.\n# **Why we have it**: To remove the need for maintainers to remember to check back on issues periodically to see if contributors have responded.\n\non:\n schedule:\n # Schedule for every day at 1:30am UTC\n - cron: '30 1 * * *'\n\npermissions:\n issues: write\n\njobs:\n stale:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/stale@v9\n with:\n days-before-stale: 7\n days-before-close: 7\n stale-issue-message: >\n 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.\n close-issue-message: >\n This issue has been automatically closed because there has been no response\n to our request for more information. With only the\n information that is currently in the issue, we don't have enough information\n to take action. Please reach out if you have or find the answers we need so\n that we can investigate further. See [this blog post on bug reports and the\n importance of repro steps](https://www.lee-dohm.com/2015/01/04/writing-good-bug-reports/)\n for more information about the kind of information that may be helpful.\n stale-issue-label: 'stale'\n close-issue-reason: 'not_planned'\n any-of-labels: 'needs:feedback'\n remove-stale-when-updated: true\n \n"
},
{
"path": "CONTRIBUTING.md",
"content": "# Contributing and Maintaining\n\nFirst, thank you for taking the time to contribute!\n\nThe 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.\n\n## Ways to contribute\n\nContributing 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:\n\n### Reporting bugs and requesting enhancements\n\nIf 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.\n\n### Suggesting new actions\n\nIdeas for future actions can be found in [issues](https://github.com/10up/actions-wordpress/issues).\n\n### Pull requests\n\nPull requests will likely be uncommon but are welcomed as necessary!\n\n## Workflow\n\nThis 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.\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2019 Helen Hou-Sandi\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "# GitHub Actions for WordPress!\n\n> 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).\n\n[](#support-level) [](https://github.com/10up/actions-wordpress/blob/master/LICENSE)\n\n[More information about GitHub Actions](https://github.com/features/actions/)\n\n## Ready to use\n\nThe following GitHub Actions are published, available to use, and actively supported by 10up.\n\n### [Deploying a plugin to the WordPress.org repository](https://github.com/10up/action-wordpress-plugin-deploy)\n\n[](https://github.com/10up/action-wordpress-plugin-deploy/blob/develop/README.md#support-level) [](https://github.com/10up/action-wordpress-plugin-deploy/releases/latest) [](https://github.com/10up/action-wordpress-plugin-deploy/blob/develop/LICENSE)\n\nWhenever 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.\n\n### [WordPress.org Plugin Build Zip Archive](https://github.com/10up/action-wordpress-plugin-build-zip)\n\n[](#support-level) [](https://github.com/10up/action-wordpress-plugin-build-zip/releases/latest) [](https://github.com/10up/action-wordpress-plugin-build-zip/blob/develop/LICENSE)\n\nThis 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.\n\n### [Deploying plugin asset/readme updates to the WordPress.org repository](https://github.com/10up/action-wordpress-plugin-asset-update)\n\n[](https://github.com/10up/action-wordpress-plugin-asset-update/blob/develop/README.md#support-level) [](https://github.com/10up/action-wordpress-plugin-asset-update/releases/latest) [](https://github.com/10up/action-wordpress-plugin-asset-update/blob/develop/LICENSE)\n\nIf 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.\n\n### [PHP linting without additional codebase dependencies](https://github.com/10up/wpcs-action)\n\n[](https://github.com/10up/wpcs-action/blob/develop/README.md#support-level) [](https://github.com/10up/wpcs-action/releases/latest) [](https://github.com/10up/wpcs-action/blob/develop/LICENSE)\n\nThis 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.\n\n### [Deploying WordPress sites to Pantheon](https://github.com/10up/pantheon-wp-deploy-action)\n\n[](#support-level) [](https://github.com/10up/pantheon-wp-deploy-action/releases/latest) [](https://github.com/10up/pantheon-wp-deploy-action/blob/trunk/LICENSE) [](https://github.com/10up/pantheon-wp-deploy-action/actions/workflows/test.yml)\n\nThe 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:\n- 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\n- The GitHub main branch deploys to the Pantheon's `Dev` environment but automatically promotes the code to the Pantheon `Test` environment\n-- We use the Pantheon's `Test` environment as our preprod environment\n- Once the changes have been tested we promote the code in the `Test` environment to `Live`\n\n### [WordPress Scanner Action](https://github.com/10up/wp-scanner-action)\n\n[](#support-level) [](https://github.com/10up/wp-scanner-action/releases/latest) [](https://github.com/10up/wp-scanner-action/blob/trunk/LICENSE.md) [](https://github.com/10up/wp-scanner-action/actions/workflows/tests.yml)\n\nGitHub 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.\n***Note**: Authentication is optional for the Wordfence Intelligence Vulnerability API.*\n\n### [Automating repository operations](https://github.com/10up/action-repo-automator)\n\n[](#support-level) [](https://github.com/10up/action-repo-automator/releases/latest) [](https://github.com/10up/action-repo-automator/blob/develop/LICENSE.md) [](https://github.com/10up/action-repo-automator/actions/workflows/codeql-analysis.yml)\n\nThis 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.\n- **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.\n- **Add Labels:** It helps with adding label to PR when PR validation pass or fail.\n- **Auto-assign Issues:** This feature helps to automatically assign issue with PR assignee when a linked PR is merged.\n- **Auto-assign PR:** It helps with assigning PR to the author.\n- **Auto request review:** It helps with request review from the team or GitHub user given in the configuration.\n- **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.\n- **Auto-label merge conflicts:** Automatically adds a label to PRs with merge conflicts, and once a conflict is resolved, the label is automatically removed.\n- **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.\n- **Auto-Sync PR branch:** Automatically keeps the pull request branch up to date with the base branch.\n- **Welcome first-time contributors:** Greet first-time contributors with a warm welcome message on their first issue or PR to the project.\n- **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.\n\n### [Publishing generated hook documentation to GitHub Pages](wp-hooks-documentor-workflow.md)\n\nYou 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/).\n\n### Validating project dependency licensing\n\nIf 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).\n\n### [Using markdown content in GitHub Actions summary](using-markdown-in-action-summary.md)\n\nIn 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.\n\n## Planned\n\n* Building a production-ready version into a `stable` branch or other location of choice.\n\n## Contributing\n\nWant to help? Check out our [contributing guidelines](CONTRIBUTING.md) to get started.\n\n## Support Level\n\n**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.\n\n## Like what you see?\n\n![\"Work](\"https://github.com/10up/.github/blob/trunk/profile/10up-github-banner.jpg\")
\n"
},
{
"path": "dotorg-plugin-asset-update/Dockerfile",
"content": "FROM debian:stable-slim\n\nLABEL \"com.github.actions.name\"=\"WordPress Plugin Readme Update\"\nLABEL \"com.github.actions.description\"=\"Deploy readme updates to the WordPress Plugin Repository\"\nLABEL \"com.github.actions.icon\"=\"upload-cloud\"\nLABEL \"com.github.actions.color\"=\"blue\"\n\nLABEL maintainer=\"Helen Hou-Sandí \"\nLABEL version=\"1.0.0\"\nLABEL repository=\"http://github.com/helen/actions-wordpress\"\n\nRUN apt-get update \\\n\t&& apt-get install -y subversion rsync git \\\n\t&& apt-get clean -y \\\n\t&& rm -rf /var/lib/apt/lists/* \\\n\t&& git config --global user.email \"10upbot+github@10up.com\" \\\n\t&& git config --global user.name \"10upbot on GitHub\"\n\nCOPY entrypoint.sh /entrypoint.sh\nENTRYPOINT [\"/entrypoint.sh\"]\n"
},
{
"path": "dotorg-plugin-asset-update/README.md",
"content": "# WordPress.org Plugin Assets Update\n\n## Moved to https://github.com/10up/action-wordpress-plugin-asset-update\n\nThe Action will continue to work as-is in your workflow files; however, we recommend migrating to the new repo for future updates.\n"
},
{
"path": "dotorg-plugin-asset-update/entrypoint.sh",
"content": "#!/bin/bash\n\n# Note that this does not use pipefail because if the grep later\n# doesn't match I want to be able to show an error first\nset -eo\n\n# Ensure SVN username and password are set\n# IMPORTANT: while secrets are encrypted and not viewable in the GitHub UI,\n# they are by necessity provided as plaintext in the context of the Action,\n# so do not echo or use debug mode unless you want your secrets exposed!\nif [[ -z \"$SVN_USERNAME\" ]]; then\n\techo \"Set the SVN_USERNAME secret\"\n\texit 1\nfi\n\nif [[ -z \"$SVN_PASSWORD\" ]]; then\n\techo \"Set the SVN_PASSWORD secret\"\n\texit 1\nfi\n\n# Allow some ENV variables to be customized\nif [[ -z \"$SLUG\" ]]; then\n\tSLUG=${GITHUB_REPOSITORY#*/}\nfi\necho \"ℹ︎ SLUG is $SLUG\"\n\nif [[ -z \"$ASSETS_DIR\" ]]; then\n\tASSETS_DIR=\".wordpress-org\"\nfi\necho \"ℹ︎ ASSETS_DIR is $ASSETS_DIR\"\n\nSVN_URL=\"http://plugins.svn.wordpress.org/${SLUG}/\"\nSVN_DIR=\"/github/svn-${SLUG}\"\n\n# Checkout just trunk and assets for efficiency\n# Stable tag will come later, if applicable\necho \"➤ Checking out .org repository...\"\nsvn checkout --depth immediates \"$SVN_URL\" \"$SVN_DIR\"\ncd \"$SVN_DIR\"\nsvn update --set-depth infinity assets\nsvn update --set-depth infinity trunk\n\necho \"➤ Copying files...\"\ncd \"$GITHUB_WORKSPACE\"\n\n# \"Export\" a cleaned copy to a temp directory\nTMP_DIR=\"/github/archivetmp\"\nmkdir \"$TMP_DIR\"\n\ngit config --global user.email \"10upbot+github@10up.com\"\ngit config --global user.name \"10upbot on GitHub\"\n\n# If there's no .gitattributes file, write a default one into place\nif [[ ! -e \"$GITHUB_WORKSPACE/.gitattributes\" ]]; then\n\tcat > \"$GITHUB_WORKSPACE/.gitattributes\" <<-EOL\n\t/$ASSETS_DIR export-ignore\n\t/.gitattributes export-ignore\n\t/.gitignore export-ignore\n\t/.github export-ignore\n\tEOL\n\n\t# Ensure we are in the $GITHUB_WORKSPACE directory, just in case\n\t# The .gitattributes file has to be committed to be used\n\t# Just don't push it to the origin repo :)\n\tgit add .gitattributes && git commit -m \"Add .gitattributes file\"\nfi\n\n# This will exclude everything in the .gitattributes file with the export-ignore flag\ngit archive HEAD | tar x --directory=\"$TMP_DIR\"\n\ncd \"$SVN_DIR\"\n\n# Copy from clean copy to /trunk, excluding dotorg assets\n# The --delete flag will delete anything in destination that no longer exists in source\nrsync -rc \"$TMP_DIR/\" trunk/ --delete\n\n# Copy dotorg assets to /assets\nrsync -rc \"$GITHUB_WORKSPACE/$ASSETS_DIR/\" assets/ --delete\n\necho \"➤ Preparing files...\"\n\nsvn status\n\nif [[ -z $(svn stat) ]]; then\n\techo \"🛑 Nothing to deploy!\"\n\texit 78\n# Check if there is more than just the readme.txt modified in trunk\n# The leading whitespace in the pattern is important\n# so it doesn't match potential readme.txt in subdirectories!\nelif svn stat trunk | grep -qvi ' trunk/readme.txt$'; then\n\techo \"🛑 Other files have been modified; changes not deployed\"\n\texit 1\nfi\n\n# Readme also has to be updated in the .org tag\necho \"➤ Preparing stable tag...\"\nSTABLE_TAG=$(grep -m 1 \"^Stable tag:\" \"$TMP_DIR/readme.txt\" | tr -d '\\r\\n' | awk -F ' ' '{print $NF}')\n\nif [ -z \"$STABLE_TAG\" ]; then\n echo \"ℹ︎ Could not get stable tag from readme.txt\";\n\tHAS_STABLE=1\nelse\n\techo \"ℹ︎ STABLE_TAG is $STABLE_TAG\"\n\n\tif svn info \"^/$SLUG/tags/$STABLE_TAG\" > /dev/null 2>&1; then\n\t\tsvn update --set-depth infinity \"tags/$STABLE_TAG\"\n\n\t\t# Not doing the copying in SVN for the sake of easy history\n\t\trsync -c \"$TMP_DIR/readme.txt\" \"tags/$STABLE_TAG/\"\n\telse\n\t\techo \"ℹ︎ Tag $STABLE_TAG not found\"\n\tfi\nfi\n\n# Add everything and commit to SVN\n# The force flag ensures we recurse into subdirectories even if they are already added\n# Suppress stdout in favor of svn status later for readability\nsvn add . --force > /dev/null\n\n# SVN delete all deleted files\n# Also suppress stdout here\nsvn status | grep '^\\!' | sed 's/! *//' | xargs -I% svn rm % > /dev/null\n\n# Now show full SVN status\nsvn status\n\necho \"➤ Committing files...\"\nsvn commit -m \"Updating readme/assets from GitHub\" --no-auth-cache --non-interactive --username \"$SVN_USERNAME\" --password \"$SVN_PASSWORD\"\n\necho \"✓ Plugin deployed!\"\n\necho \"⚠️ Please consider migrating to https://github.com/10up/action-wordpress-plugin-asset-update for the latest version of this Action\"\n"
},
{
"path": "dotorg-plugin-deploy/Dockerfile",
"content": "FROM debian:stable-slim\n\nLABEL \"com.github.actions.name\"=\"WordPress Plugin Deploy\"\nLABEL \"com.github.actions.description\"=\"Deploy to the WordPress Plugin Repository\"\nLABEL \"com.github.actions.icon\"=\"upload-cloud\"\nLABEL \"com.github.actions.color\"=\"blue\"\n\nLABEL maintainer=\"Helen Hou-Sandí \"\nLABEL version=\"1.0.0\"\nLABEL repository=\"http://github.com/helen/actions-wordpress\"\n\nRUN apt-get update \\\n\t&& apt-get install -y subversion rsync git \\\n\t&& apt-get clean -y \\\n\t&& rm -rf /var/lib/apt/lists/* \\\n\t&& git config --global user.email \"10upbot+github@10up.com\" \\\n\t&& git config --global user.name \"10upbot on GitHub\"\n\nCOPY entrypoint.sh /entrypoint.sh\nENTRYPOINT [\"/entrypoint.sh\"]\n"
},
{
"path": "dotorg-plugin-deploy/README.md",
"content": "# WordPress.org Plugin Deploy\n\n## Moved to https://github.com/10up/action-wordpress-plugin-deploy\n\nThe Action will continue to work as-is in your workflow files; however, we recommend migrating to the new repo for future updates."
},
{
"path": "dotorg-plugin-deploy/entrypoint.sh",
"content": "#!/bin/bash\n\n# Note that this does not use pipefail\n# because if the grep later doesn't match any deleted files,\n# which is likely the majority case,\n# it does not exit with a 0, and I only care about the final exit.\nset -eo\n\n# Ensure SVN username and password are set\n# IMPORTANT: while secrets are encrypted and not viewable in the GitHub UI,\n# they are by necessity provided as plaintext in the context of the Action,\n# so do not echo or use debug mode unless you want your secrets exposed!\nif [[ -z \"$SVN_USERNAME\" ]]; then\n\techo \"Set the SVN_USERNAME secret\"\n\texit 1\nfi\n\nif [[ -z \"$SVN_PASSWORD\" ]]; then\n\techo \"Set the SVN_PASSWORD secret\"\n\texit 1\nfi\n\nif [[ -z \"$GITHUB_TOKEN\" ]]; then\n\techo \"Set the GITHUB_TOKEN env variable\"\n\texit 1\nfi\n\n# Allow some ENV variables to be customized\nif [[ -z \"$SLUG\" ]]; then\n\tSLUG=${GITHUB_REPOSITORY#*/}\nfi\necho \"ℹ︎ SLUG is $SLUG\"\n\n# Does it even make sense for VERSION to be editable in a workflow definition?\nif [[ -z \"$VERSION\" ]]; then\n\tVERSION=${GITHUB_REF#refs/tags/}\nfi\necho \"ℹ︎ VERSION is $VERSION\"\n\nif [[ -z \"$ASSETS_DIR\" ]]; then\n\tASSETS_DIR=\".wordpress-org\"\nfi\necho \"ℹ︎ ASSETS_DIR is $ASSETS_DIR\"\n\nSVN_URL=\"http://plugins.svn.wordpress.org/${SLUG}/\"\nSVN_DIR=\"/github/svn-${SLUG}\"\n\n# Checkout just trunk and assets for efficiency\n# Tagging will be handled on the SVN level\necho \"➤ Checking out .org repository...\"\nsvn checkout --depth immediates \"$SVN_URL\" \"$SVN_DIR\"\ncd \"$SVN_DIR\"\nsvn update --set-depth infinity assets\nsvn update --set-depth infinity trunk\n\necho \"➤ Copying files...\"\ncd \"$GITHUB_WORKSPACE\"\n\n# \"Export\" a cleaned copy to a temp directory\nTMP_DIR=\"/github/archivetmp\"\nmkdir \"$TMP_DIR\"\n\ngit config --global user.email \"10upbot+github@10up.com\"\ngit config --global user.name \"10upbot on GitHub\"\n\n# If there's no .gitattributes file, write a default one into place\nif [[ ! -e \"$GITHUB_WORKSPACE/.gitattributes\" ]]; then\n\tcat > \"$GITHUB_WORKSPACE/.gitattributes\" <<-EOL\n\t/$ASSETS_DIR export-ignore\n\t/.gitattributes export-ignore\n\t/.gitignore export-ignore\n\t/.github export-ignore\n\tEOL\n\n\t# Ensure we are in the $GITHUB_WORKSPACE directory, just in case\n\t# The .gitattributes file has to be committed to be used\n\t# Just don't push it to the origin repo :)\n\tgit add .gitattributes && git commit -m \"Add .gitattributes file\"\nfi\n\n# This will exclude everything in the .gitattributes file with the export-ignore flag\ngit archive HEAD | tar x --directory=\"$TMP_DIR\"\n\ncd \"$SVN_DIR\"\n\n# Copy from clean copy to /trunk, excluding dotorg assets\n# The --delete flag will delete anything in destination that no longer exists in source\nrsync -rc \"$TMP_DIR/\" trunk/ --delete\n\n# Copy dotorg assets to /assets\nrsync -rc \"$GITHUB_WORKSPACE/$ASSETS_DIR/\" assets/ --delete\n\n# Add everything and commit to SVN\n# The force flag ensures we recurse into subdirectories even if they are already added\n# Suppress stdout in favor of svn status later for readability\necho \"➤ Preparing files...\"\nsvn add . --force > /dev/null\n\n# SVN delete all deleted files\n# Also suppress stdout here\nsvn status | grep '^\\!' | sed 's/! *//' | xargs -I% svn rm % > /dev/null\n\n# Copy tag locally to make this a single commit\necho \"➤ Copying tag...\"\nsvn cp \"trunk\" \"tags/$VERSION\"\n\nsvn status\n\necho \"➤ Committing files...\"\nsvn commit -m \"Update to version $VERSION from GitHub\" --no-auth-cache --non-interactive --username \"$SVN_USERNAME\" --password \"$SVN_PASSWORD\"\n\necho \"✓ Plugin deployed!\"\n\necho \"⚠️ Please consider migrating to https://github.com/10up/action-wordpress-plugin-deploy for the latest version of this Action\"\n"
},
{
"path": "using-markdown-in-action-summary.md",
"content": "# Using Markdown in the action summary\n\nIn 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.\n\nIn 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.\n\nThis page shares our results and instruction to integrate the Job summaries feature with our frequently used workflows.\n\n\n\n## ESLint\n\nFor 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.\n\n### Example workflow\n\n```yml\njobs:\n eslint:\n name: eslint\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n - name: npm install\n run: npm install\n - name: Generate linting report\n run: npm run lint:js -- --output-file eslint-report.json --format json\n continue-on-error: true\n - name: Annotate code linting results\n uses: ataylorme/eslint-annotate-action@1.2.0\n with:\n repo-token: '${{ secrets.GITHUB_TOKEN }}'\n report-json: 'eslint-report.json'\n - name: Update summary\n run: |\n npm_config_yes=true npx github:10up/eslint-json-to-md --path ./eslint-report.json --output ./eslint-report.md\n cat eslint-report.md >> $GITHUB_STEP_SUMMARY\n if: ${{ failure() }}\n```\n\n### Notes\n\n- Because this is a linting workflow, we only generate the markdown report when there are linting issues.\n- ESLint config can be complex, so we use the project linting script instead of ESLint actions.\n\n## PHPCS\n\nSimilar 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.\n\n```yml\njobs:\n phpcs:\n name: WPCS\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n - name: WPCS check\n uses: 10up/wpcs-action@stable\n with:\n use_local_config: true\n extra_args: '--report-json=./phpcs-report.json'\n - name: Update summary\n run: |\n npx github:10up/phpcs-json-to-md --path ./phpcs-report.json --output ./phpcs-report.md\n cat phpcs-report.md >> $GITHUB_STEP_SUMMARY\n if: ${{ failure() }}\n```"
},
{
"path": "wp-hooks-documentor-workflow.md",
"content": "# How to generate WordPress plugin hook documentation and deploy it to GitHub Pages\n\nYou 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/).\n\n## What you'll need\n\n* [Well-documented hooks](#hook-documentation-examples) in your WordPress plugin code\n* Node.js >= 20.0 and PHP >= 8.3 in your development environment\n* A build command for the docs, along with `@10up/wp-hooks-documentor` as `devDependencies` in your [`package.json`](#packagejson)\n* A [`wp-hooks-doc.json`](#wp-hooks-docjson) configuration file in your project root\n* A [workflow file](#example-workflow-file) in your `.github/workflows` directory\n\nThe 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.\n\n## Customization and Theming\n\nWP 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:\n\n* **Site branding**: Configure title, tagline and logo through the Docusaurus configuration file.\n* **Styling**: Customize CSS through Docusaurus theme configuration or by providing custom CSS files.\n* **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.\n\nThe 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.\n\n## Installation and Setup\n\n### Installation\n\nInstall WP Hooks Documentor as a development dependency in your project:\n\n```bash\nnpm install --save-dev @10up/wp-hooks-documentor\n```\n\n### Quick Start\n\n1. Add npm scripts in the package.json\n\n ```json\n \"init:docs\": \"wp-hooks-documentor init\",\n \"build:docs\": \"wp-hooks-documentor generate\",\n ```\n\n2. Initialize a configuration file in your project root:\n\n ```bash\n npm run init:docs\n ```\n\n2. Edit the generated [`wp-hooks-doc.json`](#wp-hooks-docjson) file to match your project settings.\n\n3. Generate documentation:\n\n ```bash\n npm run build:docs\n ```\n\n## Testing locally\n\nYou can generate and preview the documentation locally before deploying:\n\n```bash\n# Generate documentation\nnpm run build:docs\n\n# Navigate to the output directory (default: ./docs)\ncd ./docs\n\n# Start local development server\nnpm run serve\n```\n\nThe documentation site will be available at `http://localhost:3000` for local preview and testing.\n\n\n### Hook Documentation Examples\n\nWP Hooks Documentor automatically detects WordPress hooks in your PHP code. Here are examples of well-documented hooks:\n\n#### Filter Hook Example\n\n```php\n/**\n * Filters the taxonomies that should be synced.\n *\n * @since 1.0.0\n *\n * @param array $taxonomies Associative array list of taxonomies supported by current post in the format of `$taxonomy => $terms`.\n * @param WP_Post $post The post object.\n * \n * @return array Associative array list of taxonomies supported by current post in the format of `$taxonomy => $terms`.\n */\n$taxonomies = apply_filters( 'dt_syncable_taxonomies', $taxonomies, $post );\n```\n\n#### Action Hook Example\n\n```php\n/**\n * Fires the action after a post is pushed via Distributor before remote request validation.\n *\n * @since 2.0.0\n *\n * @param array|WP_Error $response The response from the remote request.\n * @param array $post_body The Post data formatted for the REST API endpoint.\n * @param string $type_url The Post type api endpoint.\n * @param int $post_id The Post id.\n * @param array $args The arguments passed into wp_insert_post.\n * @param WordPressExternalConnection $this The Distributor connection being pushed to.\n */\ndo_action( 'dt_push_external_post', $response, $post_body, $type_url, $post_id, $args, $this );\n```\n\n## Code examples 🍝\n\n### `package.json`\n\n```json\n{\n ...\n \"scripts\": {\n ...\n \"docs:init\": \"wp-hooks-documentor init\",\n \"docs:generate\": \"wp-hooks-documentor generate\",\n },\n \"devDependencies\": {\n \"@10up/wp-hooks-documentor\": \"^1.0.1\"\n }\n}\n```\n\n### `wp-hooks-doc.json`\n\nCreate this configuration file in your project root to customize the documentation generation:\n\n```json\n{\n \"title\": \"Plugin Hooks Documentation\",\n \"tagline\": \"Hooks Documentation for the plugin\",\n \"url\": \"https://example.com\",\n \"baseUrl\": \"/\",\n \"repoUrl\": \"https://github.com/username/repo\",\n \"organizationName\": \"username\",\n \"projectName\": \"my-plugin\",\n \"input\": \".\",\n \"ignoreFiles\": [\n \"/tests/\",\n \"/vendor/\",\n \"/node_modules/\"\n ],\n \"ignoreHooks\": [],\n \"outputDir\": \"./docs\",\n \"templatesDir\": \"./wp-hooks-docs\",\n \"footerStyle\": \"dark\",\n \"footerCopyright\": \"Copyright © 2025 Your Name. Built with WP Hooks Documentor.\"\n}\n```\n\n### Example workflow file\n\n#### `.github/workflows/build-docs.yml`\n\n```yml\nname: Build Hook Documentation\n\non:\n push:\n branches:\n - trunk\n\njobs:\n build-docs:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2\n\n - name: Setup proper PHP version\n uses: shivammathur/setup-php@9e72090525849c5e82e596468b86eb55e9cc5401 # v2.32.0\n with:\n php-version: 8.3\n\n - name: Setup node\n uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0\n with:\n node-version: 20\n\n - name: npm install, and build docs\n run: |\n npm install\n npm run build:docs\n \n - name: Deploy to GH Pages\n uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n publish_dir: './docs/build'\n```\n\n## Questions you may have\n\n### What if I want to build documentation but not deploy it to GitHub Pages?\n\nAbsolutely! The workflow file is just one example. You can modify it to:\n- Commit the generated documentation to your repository (e.g., in a `docs/` folder)\n- Deploy to other hosting platforms like Netlify, Vercel, or AWS S3\n- Generate documentation as part of your release process\n- Use the documentation locally for development purposes\n\n### What hook documentation formats are supported?\n\nWP Hooks Documentor works with standard WordPress PHPDoc comments. It automatically detects:\n- `apply_filters()` calls for filter hooks\n- `do_action()` calls for action hooks\n- Hook parameters and descriptions from docblock comments\n- `@since` version information\n- Parameter types and descriptions\n\n### How do I exclude certain hooks from documentation?\n\nUse the `ignoreHooks` array in your `wp-hooks-doc.json` configuration:\n\n```json\n{\n \"ignoreHooks\": [\n \"internal_hook_name\",\n ]\n}\n```\n\n\n### Can I customize the documentation theme?\n\nYes! WP Hooks Documentor uses Docusaurus, so you can:\n- Customize colors, fonts, and styling through configuration\n- Override theme by specifying a `templatesDir`\n- Add custom CSS and JavaScript\n- Modify the footer, header, and navigation\n- Add additional pages and content\n\nSee the [Docusaurus theming documentation](https://docusaurus.io/docs/styling-layout) for detailed customization options.\n\n### I have another question that's not answered here.\n\nThanks 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.\n\n## More Actions for WordPress Developers\nDo 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!\n\n\n![](\"https://github.com/10up/.github/raw/trunk/profile/10up-github-banner.jpg\")
\n
\n"
}
]