docs: adding graduation path doc #4207
Conversation
Signed-off-by: Jaydip Gabani <gabanijaydip@gmail.com>
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation about feature and API maturity stages (Alpha, Beta, GA) to guide contributors on stability requirements and compatibility guarantees. The changes align with Kubernetes API versioning conventions to establish clear expectations for feature development and promotion.
- Adds detailed Feature/API Stage Requirements section to the Backwards Compatibility document
- Updates the help.md contributor guide to reference the new maturity stage requirements
- Defines graduation criteria checklists and feature flag lifecycle guidelines
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/Backwards_Compatibility.md | Adds comprehensive Alpha, Beta, and GA stage requirements including testing, documentation, metrics, and graduation criteria |
| website/docs/help.md | Adds a new section referencing the maturity stage requirements with links to the detailed documentation |
| - **Beta** features should be well-tested, enabled by default, and production-ready | ||
| - **GA** features require comprehensive testing, backward compatibility guarantees, and performance SLOs | ||
|
|
||
| See the [Feature/API Stage Requirements](https://github.com/open-policy-agent/gatekeeper/blob/master/docs/Backwards_Compatibility.md#featureapi-stage-requirements) |
There was a problem hiding this comment.
The anchor link in the URL uses #featureapi-stage-requirements, but GitHub's automatic anchor generation for the heading '## Feature/API Stage Requirements' would create #featureapi-stage-requirements (with forward slashes converted to nothing). Verify this anchor link works correctly, as special characters in headings may not match the expected anchor format.
| - Mark feature as "Beta" in user-facing docs | ||
| - Include comprehensive usage guides and examples | ||
| - Testing must include: | ||
| - Comprehensive unit test coverage (>80% for new code) |
There was a problem hiding this comment.
The '>' symbol may render incorrectly in some Markdown parsers. Consider using '>' HTML entity or writing it as 'greater than 80%' to ensure consistent rendering across different platforms.
| - Comprehensive unit test coverage (>80% for new code) | |
| - Comprehensive unit test coverage (>80% for new code) |
docs/Backwards_Compatibility.md
Outdated
| They are disabled by default and require explicit opt-in. | ||
|
|
||
| **Requirements:** | ||
| - Feature must be behind a feature flag or opt-in configuration flag |
There was a problem hiding this comment.
This is technically not true for few APIs.
e.g https://open-policy-agent.github.io/gatekeeper/website/docs/sync/
e.g. Gatekeeper's Config CRD is alpha (v1alpha1), but it does NOT require a feature flag.
I recommend, document “with few exceptions. Starting from Gatekeeper version 3.x.0, this requirement will be enforced.”
There was a problem hiding this comment.
@ritazh the intent was to indicate that we only need feature flags for features and not the APIS, for example enable-violation-export or operation=generate vs APIS. I updated the doc to make it a little bit more clear, let me know if its still confusing. Added "startgin from gk.." line as well.
Signed-off-by: Jaydip Gabani <gabanijaydip@gmail.com>
|
@ritazh ptal. |
3 participants
What this PR does / why we need it:
Which issue(s) this PR fixes (optional, using
fixes #<issue number>(, fixes #<issue_number>, ...)format, will close the issue(s) when the PR gets merged):Fixes #
Special notes for your reviewer: