From 5288e304111cd27c7631899b4f89c22eaacdfd91 Mon Sep 17 00:00:00 2001 From: Tung Du Date: Tue, 5 Jul 2022 09:05:05 +0000 Subject: [PATCH 1/3] add markdown summary page --- using-markdown-in-action-summary.md | 67 +++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 using-markdown-in-action-summary.md diff --git a/using-markdown-in-action-summary.md b/using-markdown-in-action-summary.md new file mode 100644 index 0000000..db55cea --- /dev/null +++ b/using-markdown-in-action-summary.md @@ -0,0 +1,67 @@ +# 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 then outputing 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() }} +``` \ No newline at end of file From 550a60c586f9ae74498f302e0586ac119edce653 Mon Sep 17 00:00:00 2001 From: Tung Du Date: Tue, 5 Jul 2022 09:12:36 +0000 Subject: [PATCH 2/3] refer new page in the readme file --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 2d9425b..041d7f7 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,10 @@ This action will run PHPCS ([PHP_CodeSniffer](https://github.com/squizlabs/PHP_C If you follow the [JSDoc](https://jsdoc.app/) standard for your custom WordPress actions and filters, you can use this workflow to generate documentation for your theme/plugin and publish them to GitHub Pages. For an example of the output, see the [Distributor hook docs](https://10up.github.io/distributor/). The [linting workflow](https://github.com/10up/maps-block-apple/blob/develop/.github/workflows/linting.yml) of Block for Apple Maps is a good example how to use this action in practice. +### [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. From 8c413b90414c5eca21e1db2680070172b2a28b96 Mon Sep 17 00:00:00 2001 From: Tung Du Date: Wed, 6 Jul 2022 02:51:52 +0000 Subject: [PATCH 3/3] fix typo --- using-markdown-in-action-summary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/using-markdown-in-action-summary.md b/using-markdown-in-action-summary.md index db55cea..1a5f119 100644 --- a/using-markdown-in-action-summary.md +++ b/using-markdown-in-action-summary.md @@ -2,7 +2,7 @@ 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 then outputing the content to the `$GITHUB_STEP_SUMMARY` environment variable. +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.