docs: add version qualifier validation specification documentation#40
Conversation
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughThis PR introduces documentation for version qualifier validation by adding a new specification file (docs/qualifier-spec.md) and updating the README with navigation and cross-references to support the Version Qualifier Validation Specification for the version-tag-check GitHub Action. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related issues
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive specification documentation for version tag qualifier validation, establishing the business and functional requirements before implementation. The specification defines supported qualifier formats (SNAPSHOT, ALPHA, BETA, RC, RELEASE, HF), precedence rules for version comparison, and validation behavior for version tag sequences.
Key Changes:
- Introduces a detailed specification document covering version format, allowed qualifiers, precedence rules, and validation behavior
- Links the new specification from the main README for discoverability
- Documents non-goals and future configuration considerations
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Adds a "Documentation" section linking to the new qualifier specification |
| .github/docs/qualifier-spec.md | Introduces comprehensive specification for version qualifier validation, covering format rules, allowed qualifiers, precedence logic, sequence validation, and future considerations |
|
|
||
| ## Documentation | ||
|
|
||
| - [Version qualifier validation specification](docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action. |
There was a problem hiding this comment.
The link path 'docs/qualifier-spec.md' is incorrect. The actual file is located at '.github/docs/qualifier-spec.md' based on the diff. Update the path to match the actual location.
| - [Version qualifier validation specification](docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action. | |
| - [Version qualifier validation specification](.github/docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action. |
There was a problem hiding this comment.
@copilot: The files has been moved to correct path.
|
@miroslavpojer I've opened a new pull request, #41, to work on those changes. Once the pull request is ready, I'll request review from you. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
.github/docs/qualifier-spec.md (2)
7-12: Improve sentence structure to reduce repetitive beginnings.Lines 11–12 contain three successive sentences starting with "To" ("To support...", "To restrict...", "To define...", "To clarify..."). Consider rewording one or more sentences to improve readability.
Example revision:
The goals are: - To support version tags that extend semantic versioning with qualifiers. - To restrict qualifiers to a small, well-defined set with clear patterns. - To define precedence (ordering) rules between versions with and without qualifiers. - To clarify how sequences of tags are validated for monotonic increase. + - Support version tags that extend semantic versioning with qualifiers. + - Restrict qualifiers to a small, well-defined set with clear patterns. + - Define precedence (ordering) rules between versions with and without qualifiers. + - Clarify how sequences of tags are validated for monotonic increase.
323-335: Reduce sentence repetition in Acceptance Criteria section.Lines 329–333 contain multiple sentences starting with "It" ("It is present...", "It is discoverable...", "It clearly documents..."). Reword to improve flow.
Example revision:
The specification is considered adopted when: - It is present in the repository (e.g. `docs/qualifier-spec.md`). - It is discoverable from main documentation (e.g. linked from `README.md`). - It clearly documents: + - The specification is present in the repository (e.g. `docs/qualifier-spec.md`). + - The specification is discoverable from main documentation (e.g. linked from `README.md`). + - The following are clearly documented: - Allowed formats and qualifiers. - Precedence rules. - Validation and sequence rules. - Non-goals and future configuration considerations.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/docs/qualifier-spec.md(1 hunks)README.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
!(tests)/**/*.py
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Run Pylint on tracked Python files, excluding tests/, and aim for score 9.5 or higher
Files:
README.md.github/docs/qualifier-spec.md
🧠 Learnings (1)
📚 Learning: 2025-12-04T14:22:34.516Z
Learnt from: miroslavpojer
Repo: AbsaOSS/version-tag-check PR: 22
File: .github/workflows/release_draft.yml:63-88
Timestamp: 2025-12-04T14:22:34.516Z
Learning: The AbsaOSS/generate-release-notesv1 action supports additional parameters beyond what's documented in its README.md, including: duplicity-scope, from-tag-name, hierarchy, duplicity-icon, published-at, skip-release-notes-labels, warnings, print-empty-chapters, release-notes-title, coderabbit-support-active, coderabbit-release-notes-title, coderabbit-summary-ignore-groups, row-format-hierarchy-issue, row-format-issue, row-format-pr, and row-format-link-pr. These are all officially supported as defined in the action's action.yml file.
Applied to files:
README.md
🪛 LanguageTool
.github/docs/qualifier-spec.md
[style] ~11-~11: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...well-defined set with clear patterns. - To define precedence (ordering) rules betw...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...versions with and without qualifiers. - To clarify how sequences of tags are valid...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~329-~329: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ation (e.g. linked from README.md). - It clearly documents: - Allowed formats ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (1)
README.md (1)
9-9: Good structure for navigation and contribution guidelines.The addition of the "Contribution Guidelines" navigation link and corresponding section aligns well with the PR objectives and improves documentation navigability. The contribution guidelines content is clear and points to appropriate resources.
Also applies to: 114-124
| ### 4.3 Hotfix precedence (HF) | ||
|
|
||
| For the same `Major.Minor.Patch`, hotfix qualifiers are ordered by their numeric suffix: | ||
|
|
||
| - `v-HF1` < `v-HF2` < `v-HF10` | ||
|
|
||
| For comparisons with the bare version: | ||
|
|
||
| - A hotfix is considered a more advanced state than the same numeric version without `HF`: | ||
|
|
||
| - `1.0.1` < `1.0.1-HF1` < `1.0.1-HF2` | ||
|
|
There was a problem hiding this comment.
Clarify hotfix precedence in relation to the overall qualifier ordering.
Section 4.3 states that hotfix versions are "more advanced" than bare versions (1.0.1 < 1.0.1-HF1 < 1.0.1-HF2), but Section 4.2 defines the overall precedence as: SNAPSHOT < ALPHA < BETA < RC < RELEASE < bare version. This creates ambiguity: where does HF fit in the full ordering? Is it above the bare version (contradicting 4.2's placement)? Is it between RELEASE and bare?
To resolve, explicitly define the complete precedence order including HF. For example, clarify whether the order should be:
- Option A (HF above bare):
SNAPSHOT < ALPHA < BETA < RC < RELEASE < HF1 < HF2 < bare version, or - Option B (HF below bare):
SNAPSHOT < ALPHA < BETA < RC < RELEASE < bare version < HF1 < HF2, or another arrangement.
🤖 Prompt for AI Agents
In .github/docs/qualifier-spec.md around lines 180 to 191, Section 4.3 is
ambiguous about where HF belongs in the overall qualifier precedence; update the
section to explicitly state the complete ordering including HF and adopt the
intended relationship from the existing text (hotfixes are more advanced than
the bare version). Replace the ambiguous phrasing with a single precedence line
such as "SNAPSHOT < ALPHA < BETA < RC < RELEASE < HF1 < HF2 < ... < bare
version" and add one or two clarifying examples (e.g., "1.0.1 < 1.0.1-HF1 <
1.0.1-HF2") to make comparisons unambiguous.
| ## Documentation | ||
|
|
||
| - [Version qualifier validation specification](docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action. |
There was a problem hiding this comment.
Fix broken link to qualifier specification.
The link path docs/qualifier-spec.md does not match the actual file location at .github/docs/qualifier-spec.md. This breaks discoverability and violates the PR's acceptance criteria that the spec be "discoverable from main documentation."
Apply this diff to correct the path:
## Documentation
- - [Version qualifier validation specification](docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action.
+ - [Version qualifier validation specification](.github/docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Documentation | |
| - [Version qualifier validation specification](docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action. | |
| ## Documentation | |
| - [Version qualifier validation specification](.github/docs/qualifier-spec.md) – defines the supported version tag format, allowed qualifiers, precedence rules, and validation behavior used by this action. |
🤖 Prompt for AI Agents
In README.md around lines 110 to 112, the link to the version qualifier spec
points to docs/qualifier-spec.md but the actual file lives at
.github/docs/qualifier-spec.md; update the Markdown link target to
.github/docs/qualifier-spec.md so the documentation is discoverable from the
main README.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/qualifier-spec.md (2)
10-12: Reduce repetition in sentence structure.Lines 10–12 begin three successive sentences with the word "To". While the content is clear, the repetitive structure can be improved for readability. Consider rewording at least one sentence to vary the opening.
Current:
- To support version tags…
- To restrict qualifiers…
- To define precedence…
- To clarify how sequences…
Suggested revision:
- Support version tags that extend semantic versioning with qualifiers.
- Restrict qualifiers to a small, well-defined set with clear patterns.
- Define precedence (ordering) rules between versions with and without qualifiers.
- Clarify how sequences of tags are validated for monotonic increase.
327-333: Reduce repetition in sentence structure (acceptance criteria).Lines 328–332 begin three successive sentences with "It", creating repetitive structure. Consider varying the sentence openings for better readability.
Current:
- It is present in the repository…
- It is discoverable from main documentation…
- It clearly documents:…
Suggested revision:
- The spec is present in the repository…
- It is discoverable from main documentation…
- Contents should clearly document:…
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/qualifier-spec.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
!(tests)/**/*.py
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Run Pylint on tracked Python files, excluding tests/, and aim for score 9.5 or higher
Files:
docs/qualifier-spec.md
🪛 LanguageTool
docs/qualifier-spec.md
[style] ~11-~11: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...well-defined set with clear patterns. - To define precedence (ordering) rules betw...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...versions with and without qualifiers. - To clarify how sequences of tags are valid...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~329-~329: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ation (e.g. linked from README.md). - It clearly documents: - Allowed formats ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
| ### 3.4 Release Candidate (RC) | ||
|
|
||
| - Prefix: `RC` | ||
| - Numeric suffix: 1–2 digits (`1`–`99`) | ||
| - Overall pattern: `RC[0-9]{1,2}` | ||
|
|
||
| Examples: | ||
|
|
||
| - Valid: `1.0.0-RC1`, `1.0.0-RC2`, `1.0.0-RC10` | ||
| - Invalid: `1.0.0-RC`, `1.0.0-RC001`, `1.0.0-Rc1`, `1.0.0-rc1` | ||
|
|
||
| ### 3.5 RELEASE | ||
|
|
||
| - Literal: `RELEASE` | ||
| - Pattern: exactly `RELEASE` | ||
|
|
||
| Examples: | ||
|
|
||
| - Valid: `1.0.0-RELEASE` | ||
| - Invalid: `1.0.0-release`, `1.0.0-RELEASE1` | ||
|
|
||
| > Note: `1.0.0-RELEASE` is distinct from `1.0.0` (no qualifier). Both are “final-like” states but have different precedence. | ||
|
|
||
| ### 3.6 HOTFIX (HF) | ||
|
|
||
| - Prefix: `HF` | ||
| - Numeric suffix: 1–2 digits (`1`–`99`) | ||
| - Overall pattern: `HF[0-9]{1,2}` | ||
|
|
||
| Examples: | ||
|
|
||
| - Valid: `1.0.1-HF1`, `1.0.1-HF2`, `1.0.1-HF10` | ||
| - Invalid: `1.0.1-HF`, `1.0.1-HF001`, `1.0.1-hf1` | ||
|
|
There was a problem hiding this comment.
Clarify leading-zero handling in RC and HF numeric patterns.
Lines 103 and 126 use the regex pattern [0-9]{1,2} to describe RC and HF suffixes, but the spec states the allowed range as "1–2 digits (1–99)" (lines 102, 125). The regex notation technically matches strings like RC00, RC01, HF00, etc., which fall outside the intended 1–99 range.
For clarity during implementation, explicitly state whether leading zeros (e.g., RC01, HF02) are accepted or rejected. Consider updating the pattern notation or adding a clarifying sentence.
For example: "Numeric suffix: 1–2 digits, in the range 1–99, without leading zeros (e.g., RC1, RC99, but not RC01 or RC001)."
🤖 Prompt for AI Agents
In docs/qualifier-spec.md around lines 99 to 132, the RC and HF numeric regex
"[0-9]{1,2}" currently allows values like "00" or "01" which contradicts the
intended range 1–99; update the spec to explicitly forbid leading zeros and show
the intended valid examples and pattern (e.g., state "Numeric suffix: 1–2 digits
in the range 1–99, without leading zeros — valid: RC1, RC99; invalid: RC01,
RC00, RC001") and either replace the regex with one that enforces no leading
zeros (or add a clarifying sentence) so implementers know to reject values with
leading zeros.
| ## 4. Version Precedence Rules | ||
|
|
||
| ### 4.1 Numeric precedence | ||
|
|
||
| Versions are compared first by their numeric components: | ||
|
|
||
| 1. `Major` | ||
| 2. `Minor` | ||
| 3. `Patch` | ||
|
|
||
| Qualifiers are only considered if the numeric components are equal. | ||
|
|
||
| Examples: | ||
|
|
||
| - `2.0.0-SNAPSHOT` > `1.9.9-RELEASE` | ||
| - `1.1.0-ALPHA` > `1.0.5-HF2` | ||
|
|
||
| ### 4.2 Qualifier precedence for the same numeric version | ||
|
|
||
| For the same `Major.Minor.Patch`, qualifier precedence is: | ||
|
|
||
| 1. `SNAPSHOT` (lowest) | ||
| 2. `ALPHA` | ||
| 3. `BETA` | ||
| 4. `RCx` (ordered by `x`) | ||
| 5. `RELEASE` | ||
| 6. No qualifier (highest for that numeric base) | ||
|
|
||
| Formally, for version `v = Major.Minor.Patch`: | ||
|
|
||
| - `v-SNAPSHOT` < `v-ALPHA` < `v-BETA` | ||
| - `v-BETA` < `v-RC1` < `v-RC2` < … < `v-RC99` | ||
| - Any `v-RC*` < `v-RELEASE` | ||
| - `v-RELEASE` < `v` | ||
|
|
||
| Example ordering: | ||
|
|
||
| - `1.0.0-SNAPSHOT` | ||
| - `1.0.0-ALPHA` | ||
| - `1.0.0-BETA` | ||
| - `1.0.0-RC1` | ||
| - `1.0.0-RC2` | ||
| - `1.0.0-RELEASE` | ||
| - `1.0.0` | ||
|
|
||
| ### 4.3 Hotfix precedence (HF) | ||
|
|
||
| For the same `Major.Minor.Patch`, hotfix qualifiers are ordered by their numeric suffix: | ||
|
|
||
| - `v-HF1` < `v-HF2` < `v-HF10` | ||
|
|
||
| For comparisons with the bare version: | ||
|
|
||
| - A hotfix is considered a more advanced state than the same numeric version without `HF`: | ||
|
|
||
| - `1.0.1` < `1.0.1-HF1` < `1.0.1-HF2` | ||
|
|
||
| --- |
There was a problem hiding this comment.
Clarify HF (hotfix) precedence in the overall qualifier hierarchy.
Section 4.2 defines the main precedence order (lines 154–161) as: SNAPSHOT < ALPHA < BETA < RCx < RELEASE < no qualifier. However, section 4.3 states that hotfixes are "more advanced" than the base version (1.0.1 < 1.0.1-HF1), which would place HF above the base version.
This creates an ambiguity: where exactly does HF fit in the precedence hierarchy? Is it RELEASE < HF < no qualifier, or does HF have different semantics that bypasses the main precedence order? The spec must explicitly place HF relative to RELEASE and the unqualified base version to avoid confusion during implementation.
Proposed fix: Update section 4.2 to include HF in the overall precedence order, or clarify in section 4.3 whether HF qualifiers follow the same precedence rules as other qualifiers or whether they have special semantics. For example:
### 4.2 Qualifier precedence for the same numeric version
For the same `Major.Minor.Patch`, qualifier precedence is:
1. `SNAPSHOT` (lowest)
2. `ALPHA`
3. `BETA`
4. `RCx` (ordered by `x`)
5. `RELEASE`
6. `HFx` (ordered by `x`)
7. No qualifier (highest for that numeric base)Or, if HF qualifiers are meant to represent patches/fixes after the base release and should not follow the standard precedence, clarify that special case explicitly.
🤖 Prompt for AI Agents
In docs/qualifier-spec.md around lines 135 to 192, the spec is ambiguous about
where HF (hotfix) qualifiers belong relative to RELEASE and the unqualified base
version; clarify by explicitly inserting HF into the qualifier precedence or by
stating HF is a special case. Update section 4.2 to show HFx ordered by numeric
suffix (e.g., ... RELEASE, HFx, No qualifier) or add a short sentence in 4.3
saying HF qualifiers are ranked after RELEASE but before the bare version (and
ordered by HF number), ensuring examples and formal statements reflect that
placement.
miroslavpojer
deleted the
feature/38-Add-version-qualifier-validation-specification-documentation
branch
Summary
This pull request introduces the business/functional specification for version tag qualifiers and their validation in the version-tag-check action.
The specification documents:
Major.Minor.Patch[-qualifier]SNAPSHOTALPHABETARC[0-9]{1,2}RELEASEHF[0-9]{1,2}Major,Minor,Patch)SNAPSHOT < ALPHA < BETA < RC < RELEASE < no qualifierRC1 < RC2,HF1 < HF2)This PR is documentation-only and does not change the current validation logic of the action.
Release Notes:
docs/qualifier-spec.mdcontaining the version qualifier validation specification.README.md(Documentation section) so users can easily find the rules governing version tags.Motivation
Notes
Closes #38
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.