[Meta] Making documentation issues automatically

[peternied]

@VachaShah has been looking to add features to ensure we've got documentation on more features with ways to create issues in this repository. I would recommend that the maintainers from this repository see if there is anything that would like to comment on or make suggestions before this rolls out to all repositories.

FYI: @keithhc2 @alicejw-aws @Naarcha-AWS @hdhalter

See:

• Overall effort to make documentation label create issues in this repository [PROPOSAL] Create a workflow for documenting features project-meta#43
• Instance of the GitHub workflow on a repository that will create theses issues after a maintainer adds 'needs-documentation' label on a pull request Adding workflow for creating documentation issues security#1857

[Naarcha-AWS]

@peternied: I'm not unopposed to this, although I do fear this might translate to developers assuming that adding a "needs-documentation" label will be enough for writers to move forward with documentation when the writer might require more resources than just an issue or PR. The benefit of a manual process is having another filter in which engineers can provide additional resources that might not be in a PR.

[hdhalter]

Thanks for the call today, Peter and Vacha! This feature will be a great improvement. On our side, we will provide the template for what the issue contains (title, fields, etc.) and what text to include in the originating PR. We'll let you know when we have a draft prepared.

[hdhalter]

Hi all, here is a proposal for the workflow:

1. A developer creates a PR that fixes a bug or adds a new feature in OpenSearch.
2. If the change requires a documentation update, the developer adds the label "needs documentation".
3. The developer merges the PR.
4. Upon the merging process, an ISSUE is automatically created in the documentation repository. The ISSUE will be created from the documentation-issue.md template. (Note that this template does not exist today, so it would need to be created).
5. The program populates the ISSUE with the following information:
   • Title: the same as the PR (the developer can rename the title later if inappropriate)
   • Description - the PR number, Assignee, Version, etc. (up for discussion, but anything from the PR that would be helpful).
6. The program populates the PR with the following information in a comment: “A documentation issue has been created: <#issue #>. Please open the issue and provide any information that is relevant for this change. For example, features impacted, version, links, or resources.
   Please let us know if this sounds feasible @VachaShah and @peternied. Thanks!

[hdhalter]

Hi @VachaShah - I see there is a new issue in the doc repo that came from "opensearch-trigger-bot": #646.

Is this a result of this process or something else?

[Naarcha-AWS]

Looks like this has already been implemented in the security repository, if we look at issues open by the trigger bot: https://github.com/opensearch-project/documentation-website/issues/created_by/app/opensearch-trigger-bot.

@VachaShah: Should we add a couple more repositories for the bot to make issues against?