GitHub Action for 'docs:build' step after documentation changes

[bph]

What problem does this address?

On top of documentation pages in the block-editor handbook you'll find an "Edit" link, that leads you to this GitHub repo and you can make changes easily on a handbook page. It automatically creates a branch for contributors who already have a fork. Once the edits are done, the contributor submits the changes. However the changes can't be merged until the command npm run docs:build on a local computer.

It feels like a hurdle to do fast incremental updates on documentation pages.

What is your proposed solution?

Maybe there is a way to create a GitHub action that runs the command npm run docs:build after changes in the ./docs folder, similar to creating a plugin build for every code PR?

[fabiankaegy]

I also ran into this several times. I'm not sure what all the circumstances are where running the build command is actually required. But it would definitely be nice to remove that step especially since the documentation is something that should be approachable for first-time contributors and as easy as possible to maintain.

[fabiankaegy]

Here is an example of a PR where this caused friction: https://github.com/WordPress/gutenberg/pull/42276

You can see the failed static analysis GitHub Action here: https://github.com/WordPress/gutenberg/runs/7254588075?check_suite_focus=true#step:7:33

[gziolo]

One way to improve the workflow could be to automatically run npm run docs:build with the GitHub action. The commit will get created if the changes need to be applied by the same bot that we use to control releases for the Gutenberg plugin or npm publishing. Example of the code that adds commits:

https://github.com/WordPress/gutenberg/blob/ed5813c1325b8d6a09df7dd1bda00a8d90faf820/.github/workflows/build-plugin-zip.yml#L128-L134

There is a package that contains some automation that happens when different actions get triggered for PRs and issues:

https://github.com/WordPress/gutenberg/tree/trunk/packages/project-management-automation

To start, we could use a unique label or keyword in the comment to manually trigger the GitHub action that would run this command on the branch that contains documentation changes that need some post-processing.

[ryanwelcher]

This came up in the Block Editor Documentation Issue Scrub. It's not strictly related to adding/changing the documentation but rather the technical process. Wondering what the next steps are to move this forward?

[bph]

@gziolo had an idea above. . Not sure how feasible that is and how to go about it.

[bangank36]

@gziolo I have added the build docs step on this https://github.com/WordPress/gutenberg/pull/54411 but it is not working properly yet

• There is a test PR against it at https://github.com/WordPress/gutenberg/pull/54412

I tested the steps on my own forked repo and the build docs & commit manifest steps working correctly https://github.com/bangank36/gutenberg/actions/runs/6159922145/job/16715714683

• At first, there is an issue with Detached HEAD state, and be fixed with fetch-depth: 0 for Action checkout
• But now the issue happen again on #54412, it is something related to forked repo permission? As I have tried pull_request and pull_request_target with no luck just yet

Update

1. Found the mistake, the test PR #54412 is made against Wordpress/gutenberg trunk facepalm, I remade new test PR in my own repo since the #54411 is not merged to trunk yet, therefore Action can not find the branch
2. Missing checkout head branch before running npm run docs:build

New test branch

is at https://github.com/bangank36/gutenberg/pull/17

• All Rebuild manifest.json file passed
• Latest commit with modified manifest.json is pushed to the head branch by gitbot

cc @annezazu

[bangank36]

@ryanwelcher @bph given the submitted PR for docs build step, who do you think should I ping to get the issue moved forward? Thanks