workflow: create docs-check

[ES-Alexander]

Provides a fail indicator for PRs with the "docs-needed" label.

Process found at https://stackoverflow.com/a/71504928/15326510

DO NOT MERGE until BlueOS-1.1 base docs have been published.

[ES-Alexander]

• BlueOS-1.1 branch is now merged (and published)
• There's a new BlueOS-devel-temp branch, for documenting changes that are not yet in a release
  • I'm thinking this can stay as un-published and unstable, and just gets PR'd into the latest version branch when a new version is released
• I've added docs-needed tags to all the relevant and currently undocumented PRs, made since the 1.1.0-beta16 release

I believe this PR can now be merged :-)

[patrickelectric]

Just to be sure, will this block PRs that will reflect in documentation change for 1.1 ?

[ES-Alexander]

will this block PRs that will reflect in documentation change for 1.1 ?

@patrickelectric I'm not sure what you mean by this. The idea is it will block merging PRs that are marked as needing documentation (i.e. with the docs-needed label) until that documentation has been written (at which point we will change the label to docs-complete, and it will no longer be blocked).

I'm considering "written" to be "an approved PR into the BlueOS-devel-temp branch" (which is not automatically used in the generated public documentation). Then when the change itself gets merged in we can merge the docs PR as well. Once we're ready to make a new release (e.g. BlueOS-1.1.0-beta.17), as part of that process, we should merge the current devel-temp docs branch into the relevant version branch (e.g. BlueOS-1.1), at which point it will then be included in the generated docs.

[patrickelectric]

unlabeled is unnecessary, since we are tracking a label.

Suggested change

	types:
	- opened
	- labeled
	- unlabeled
	on:
	pull_request:
	types: [opened, labeled]

[ES-Alexander]

I think the CI check should still run on an unlabeled PR - worst case it's just seen as one more passing test, but best case it might remind the submitter to add a docs label if it's relevant to do so. We also want it to re-run if the docs-needed label gets removed (e.g. if it was put there accidentally), which I'm assuming this would help with?

[patrickelectric]

Probably you'll prefer this: https://github.com/marketplace/actions/comment-pull-request

[ES-Alexander]

I feel like a CI check is more relevant - it's not necessary to have an automated comment history saying "please write docs" if they haven't been written yet, and a comment is less of a mental block to merging something in (the point being to make the merger stop and think before doing so if there's a 'failing test').