feat(docs): add workflow to generate documentation on PR merge #12681
Conversation
Co-authored-by: Rod Vagg <rod@vagg.org>
|
@virajbhartiya can you resolve the conflict with |
|
Hey @rvagg, I have resolved the conflicts in the PR |
|
@rvagg any suggestions on why is the workflow failing? |
|
Failing because you need to install system dependencies for the build in check.yml, you'll see: - uses: ./.github/actions/install-system-dependencies
- uses: ./.github/actions/install-go
- uses: ./.github/actions/make-depsthese are required to perform the actions you need, so you'll have to do it again in your new job but, having said that, it's not cheap, so maybe this should all be in a single job so that's all done once and it's just the docsgen-cli bit that's done separately. So how about this:
I'm still not convinced this is a great idea, it might get in the way. So we'll need to have a collective chat with others before we proceed. |
|
Hey @rvagg thanks for the review, I have currently modified it accordingly, renamed check.yml to check-and-gen.yml and added it in the same file. We can discuss regarding this on slack wtih other how to go ahead with this PR |
|
I know there have been verbal conversation on this one. Did we write out the next steps? |
|
Didn't write it out, but next steps are to get this completed and merged and then experience it live and decide whether we hate it or love it and whether it's a QoL improvement on balance. |
| generate-docs: | ||
| name: Generate Documentation | ||
| runs-on: ubuntu-latest | ||
| if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/release/')) |
There was a problem hiding this comment.
I'm unsure about this and whether a merge into one of these branches would trigger the job as well, we only want it to run on the PR branch, strictly. So this line worries me a little and it needs verification, somehow, or we need a subject-matter expert to help.
There was a problem hiding this comment.
@BigLep maybe something to pull IPDX into to help review.
There was a problem hiding this comment.
@galargh : do you know offhand whether this will only run on pushes to PR branches and not on master or release branches?
There was a problem hiding this comment.
That's the opposite of what this conditional says.
The conditional is: accept a workflow run which was triggered by a push event to either master or release/* branch.
| git config user.email "41898282+github-actions[bot]@users.noreply.github.com" | ||
| git add . | ||
| git commit -m "docs: update API documentation via docsgen-cli" | ||
| git push |
There was a problem hiding this comment.
Another thing I'm wondering is if this is going to work to fork-branches, if this is run a a filecoin-project GHA runner, will we always have permissions to push back into the PR branch? Do we need to ensure we have a "can edit branches" thing turned on in our repo? Do we need to do anything else to make this work?
There was a problem hiding this comment.
As currently configured, this will be run on push events to master or release/*. But it won't work because they are protected. To overcome this, one would have to use a personal access token for a user that can disregard the branch protection rules.
| @@ -33,8 +33,6 @@ jobs: | |||
| - uses: ./.github/actions/make-deps | |||
| - run: make gen | |||
There was a problem hiding this comment.
Probably too big a leap for now, but I'd actually like to move docsgen out of make gen so we can run it here. Maybe for now we just do docsgen-cli and if it works OK we'll consider expanding it.
There was a problem hiding this comment.
FYI, https://github.com/ipdxco/github-as-code/blob/master/.github/workflows/fix.yml is a working example of a workflow that runs on PRs and writes to PR branches.
| generate-docs: | ||
| name: Generate Documentation | ||
| runs-on: ubuntu-latest | ||
| if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/release/')) |
There was a problem hiding this comment.
That's the opposite of what this conditional says.
The conditional is: accept a workflow run which was triggered by a push event to either master or release/* branch.
| git config user.email "41898282+github-actions[bot]@users.noreply.github.com" | ||
| git add . | ||
| git commit -m "docs: update API documentation via docsgen-cli" | ||
| git push |
There was a problem hiding this comment.
As currently configured, this will be run on push events to master or release/*. But it won't work because they are protected. To overcome this, one would have to use a personal access token for a user that can disregard the branch protection rules.
Related Issues
Closes #12233
Proposed Changes
Add a workflow that run
make docsgen-cliwhenever the PR is mergedChecklist