dheeraj12347 opened a new pull request, #13904:
URL: https://github.com/apache/cloudstack/pull/13904
## Description
This PR completes the remaining `allowedValues` annotation work for the
CloudStack API parameters identified during the allowed-values audit and adds a
CI check to prevent missing annotations from being introduced.
### Changes
- Added `allowedValues` annotations to the remaining statically-known
enum-like API parameters.
- Added handling for the `CheckAndRepairVolumeCmd.repair` parameter and its
associated inner enum.
- Added `scripts/check_allowed_values.py` to detect string parameters whose
descriptions specify a closed set of valid/possible/allowed values but do not
declare `allowedValues`.
- Extended the checker to cross-reference inner enums in command classes
with their `@Parameter` fields.
- Added unit tests in `scripts/test_check_allowed_values.py` covering:
- valid-value extraction
- `and`-separated values
- open-ended protocol values
- string vs non-string parameters
- missing `allowedValues`
- existing `allowedValues`
- inner enum detection
- enum parameters using `allowedValueType`
- Added the allowed-values check to the CloudStack GitHub Actions CI
workflow.
### Validation
The following checks pass locally:
```text
python3 -m unittest scripts.test_check_allowed_values -v
Ran 13 tests ... OK
python3 -m py_compile \
scripts/check_allowed_values.py \
scripts/test_check_allowed_values.py
python3 scripts/check_allowed_values.py
No missing allowedValues annotations found.
git diff --cached --check
The CI workflow added by this PR runs:
python3 scripts/check_allowed_values.py
against the CloudStack repository.
Scope
This check is intended to identify statically-known, closed sets of allowed
values. Deployment-dependent values that require runtime discovery are not
treated as static allowedValues.
---
# 3. Why this description is appropriate for your proposal
This isn't arbitrary wording.
Your proposal explicitly defines PR4/D4 as:
> **Tier 4 annotations + CI lint rules**, including a **description-pattern
check + cross-reference check**. :contentReference[oaicite:1]{index=1}
And your Phase 4 plan specifically says the CI should:
- detect descriptions mentioning `"valid values"` or similar;
- detect missing `allowedValues`;
- cross-reference inner enums against `@Parameter` fields.
:contentReference[oaicite:2]{index=2}
So the PR description is describing the actual deliverable you committed to.
---
# 4. Add this as the "Why" paragraph if GitHub asks for more context
If you want a short explanation of **why this change is needed**, use this:
```markdown
## Why
CloudStack already knows many API parameters have a fixed set of valid
values, but some of this information is only present in human-readable
parameter descriptions. This makes it difficult for clients such as CloudMonkey
to consume the information reliably.
The `allowedValues` metadata introduced in the earlier API-discovery work
provides a structured representation of these values. This PR completes the
remaining static annotations identified during the audit and adds a CI guard so
that future parameters with explicitly documented closed value sets are less
likely to miss the metadata.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
