[META] Documentation website enhancements w/ engineering support

[vagimeli]

Is your feature request related to a problem? Please describe

Yes. The Docs as Code process can be improved by adding sign offs to development PRs. This would ensure documentation is created and managed alongside the code.

Describe the solution you'd like

Add a task list item (Documentation) through GitHub Actions.

Describe alternatives you've considered

No response

Additional context

No response

---

Issues:

• opensearch-project/documentation-website#6400

[vagimeli]

cc: @hdhalter @kolchfa-aws

[kolchfa-aws]

Specifically, we're proposing the following changes:

• Adding a mechanism so that a developer can indicate if documentation is required for the feature.
• If documentation is required, preventing the dev PR from being merged until a documentation PR is in place in the doc repo.
• If the feature adds new APIs, for each new API, the documentation PR must contain a filled out API Template, that provides all parameters, whether they are required or optional, default values, descriptions, and types.

[peterzhuamazon]

Needs more discussion on this specific request. Will add more acceptance criteria later.

[hdhalter]

From Barani: We will break down this issue in to multiple tasks: 1.) Add mandatory "Need documentation" checklist to all PR's ( similar to DCO check) 2.) If documentation checklist is ticked, automated workflow will add documentation label to the PR and also create an issue in documentation repo referencing the PR.

We can implement similar logic for issues as well.

We can work on gating PR merge as future enhancement.

[peterzhuamazon]

Have some discussion with Heather offline, and seems like this requires some more testing. There are generally two models as in opt-in vs. opt-out.

If we do the opt-in model where developers need to check a box or add a label, it does not guarantee the issue creation if the label is missed. If we do the opt-out model then the timing of creating such issues and avoid unnecessary noise is key.

Still need some thoughts and discussion or even a one pager / poc before proceed with implementation.

[vagimeli]

Have some discussion with Heather offline, and seems like this requires some more testing. There are generally two models as in opt-in vs. opt-out.

If we do the opt-in model where developers need to check a box or add a label, it does not guarantee the issue creation if the label is missed. If we do the opt-out model then the timing of creating such issues and avoid unnecessary noise is key.

Still need some thoughts and discussion or even a one pager / poc before proceed with implementation.

Some ideas to consider: https://about.gitlab.com/blog/2022/10/12/five-fast-facts-about-docs-as-code-at-gitlab/

[peterzhuamazon]

Working on GitHubApp POC and will send one pager design later.

[peterzhuamazon]

Seems like core already have a basic workflow for creating the docs issues: https://github.com/opensearch-project/OpenSearch/blob/main/.github/workflows/create-documentation-issue.yml

[peterzhuamazon]

We have decided on this workflow:

1. Use core/plugin issue template to allow contributors to select whether they need to add a doc for their feature with needs-documentation label.
2. The label will trigger a issue creation in documentation-website repo.
3. The doc issue will inherit core/plugin issue on assigning users, add release branch, and more.

We will also add other checks later such as block PR merge, link backports to original opened issues, and more later, to help the docs team and core/plugin team avoid missing documentations, and start working on those early on.

Thanks.