docs(ci): adds generated reference workflow by lukegalbraithrussell · Pull Request #197 · slackapi/slack-cli

docs(ci): adds generated reference workflow by lukegalbraithrussell · Pull Request #197 · slackapi/slack-cli

Summary

This PR adds a manual dispatch workflow to be run after release to update the CLI reference docs

This PR also manually updates the CLI reference docs using the recently updated version of docgen now in main.

I have a PR preview of this but idk if i should be dropping the link in a public PR hmmm

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.92%. Comparing base (859d4f1) to head (c4ea92e).
⚠️ Report is 18 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #197      +/-   ##
==========================================
- Coverage   62.94%   62.92%   -0.03%     
==========================================
  Files         212      212              
  Lines       21782    21782              
==========================================
- Hits        13711    13706       -5     
- Misses       7009     7012       +3     
- Partials     1062     1064       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

zimeg changed the title ~~Docs CI: adds generated reference workflow + adds manual update of generated reference docs~~ docs(ci): adds generated reference workflow + adds manual update of generated reference docs

zimeg added docs

M-T: Documentation work only

M-T: Changes to compilation and CI processes

labels

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📚 LGTM! Thanks for following up on #194 and #195!

I left a few comments around the workflow that IMHO should be addressed but otherwise docs changes are looking great. We could perhaps make a separate PR for the generated reference workflow too?

Comment on lines +3 to +4

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👁️‍🗨️ thought: Adding on "version" tags might be interesting! Otherwise we will need to add this to our release runbooks.

📣 ramble: So open to saving this for follow ups of course.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗣️ note: Ugh that was more clear in mind... I meant to suggest "on new tagged releases the workflow should run" but I forget the syntax!


		- name: Generate a GitHub token
		id: ghtoken
		uses: actions/create-github-app-token@v2

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💔 todo: We should use pinned versions here though I don't think the healthscore has released such a check yet...

📫 note: I can soon add these versions if needed!

		workflow_dispatch:

		jobs:
		update-docs:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔐 todo: This'll also need some set of permissions. Do let me know if I can help with this!

lukegalbraithrussell changed the title ~~docs(ci): adds generated reference workflow + adds manual update of generated reference docs~~ docs(ci): adds generated reference workflow

@zimeg this PR is now just the workflow! reference updates are now in #198

🗣️ Removed this from the next milestone for now. I think we want to refine our release process to autogenerate docs during the tag? IIRC suggestion has been floated for:

And perhaps this can be included in workflows somehow in the future?

zimeg mentioned this pull request

2 tasks

@lukegalbraithrussell Thanks for starting conversation on how we keep documentation current with a changing release process!

A change to use the following command landed in #228 for improving how we update installation links and #229 was opened to include similar docgen updates:

$ make tag RELEASE_VERSION=3.1.4

I'm so curious if we can follow up on these to use PRs as part of our release process automations - let's continue these explorations? 👾

🗣️ Wanting to keep track of our progress in automating these updates! The above PRs were a success in the most recent release v3.8.0!

Some follow up seems needed still though:

Pushing to main skips perhaps useful checks that CI reviews give. We can perhaps have a bot open these changes as PRs? I'm unsure if tagging can still be automated though...
Running docgen at the time of release seems late IMHO. It'd be most excellent if these changes were included with the related PR since we can now pin documentation to a tag!

I'm open to keeping this PR around for more discussion on this topic!