gh-dhofheinz-open-plugins-plugins-marketplace-validator-plugin/commands/best-practices/validate-versioning.md

Operation: Validate Versioning

Validate version strings against Semantic Versioning 2.0.0 specification.

Parameters from $ARGUMENTS

• version: Version string to validate (required)
• strict: Enforce strict semver (no pre-release/build metadata) (optional, default: false)

Semantic Versioning Standard

Base Pattern: MAJOR.MINOR.PATCH (e.g., 1.2.3)

Strict Format: ^[0-9]+\.[0-9]+\.[0-9]+$

Extended Format (with pre-release and build metadata):

• Pre-release: 1.2.3-alpha.1, 2.0.0-beta.2, 1.0.0-rc.1
• Build metadata: 1.2.3+20241013, 1.0.0+build.1
• Combined: 1.2.3-alpha.1+build.20241013

Valid Examples

Strict Semver (OpenPlugins recommended):

• 1.0.0 - Initial release
• 1.2.3 - Standard version
• 2.5.13 - Double-digit components
• 0.1.0 - Pre-1.0 development

Extended Semver (allowed):

• 1.0.0-alpha - Alpha release
• 1.0.0-beta.2 - Beta release
• 1.0.0-rc.1 - Release candidate
• 1.2.3+20241013 - With build metadata

Invalid Examples

• 1.0 - Missing PATCH
• v1.0.0 - Leading 'v' prefix
• 1.0.0.0 - Too many components
• 1.2.x - Placeholder values
• latest - Non-numeric
• 1.0.0-SNAPSHOT - Non-standard identifier

Workflow

1. Extract Version from Arguments

   Parse $ARGUMENTS to extract version parameter
   If version not provided, return error
   

2. Execute Semantic Version Checker

   Execute .scripts/semver-checker.py "$version" "$strict"
   
   Exit codes:
   - 0: Valid semantic version
   - 1: Invalid format
   - 2: Missing required parameters
   - 3: Strict mode violation (valid semver, but has pre-release/build)
   

3. Parse Version Components

   Extract components:
   - MAJOR: Breaking changes
   - MINOR: Backward-compatible features
   - PATCH: Backward-compatible fixes
   - Pre-release: Optional identifier (alpha, beta, rc)
   - Build metadata: Optional metadata
   

4. Return Validation Report

   Format results:
   - Status: PASS/FAIL/WARNING
   - Version: <provided-version>
   - Valid: yes/no
   - Components: MAJOR.MINOR.PATCH breakdown
   - Pre-release: <identifier> (if present)
   - Build: <metadata> (if present)
   - Score impact: +5 points (if valid)
   

Examples

# Valid strict semver
/best-practices versioning version:1.2.3
# Result: PASS - Valid semantic version (1.2.3)

# Valid with pre-release
/best-practices versioning version:1.0.0-alpha.1
# Result: PASS - Valid semantic version with pre-release

# Invalid format
/best-practices versioning version:1.0
# Result: FAIL - Missing PATCH component

# Strict mode with pre-release
/best-practices versioning version:1.0.0-beta strict:true
# Result: WARNING - Valid semver but not strict format

# Invalid prefix
/best-practices versioning version:v1.2.3
# Result: FAIL - Contains 'v' prefix (use 1.2.3)

Error Handling

Missing version parameter:

ERROR: Missing required parameter 'version'

Usage: /best-practices versioning version:<semver>

Example: /best-practices versioning version:1.2.3

Invalid format:

ERROR: Invalid semantic version format

The version must follow MAJOR.MINOR.PATCH format.

Examples:
- 1.0.0 (initial release)
- 1.2.3 (standard version)
- 2.0.0-beta.1 (pre-release)

Output Format

Success (Valid Semver):

✅ Semantic Versioning: PASS

Version: 1.2.3
Format: MAJOR.MINOR.PATCH
Valid: Yes

Components:
- MAJOR: 1 (breaking changes)
- MINOR: 2 (new features)
- PATCH: 3 (bug fixes)

Quality Score Impact: +5 points

The version follows Semantic Versioning 2.0.0 specification.

Success with Pre-release:

✅ Semantic Versioning: PASS

Version: 1.0.0-beta.2
Format: MAJOR.MINOR.PATCH-PRERELEASE
Valid: Yes

Components:
- MAJOR: 1
- MINOR: 0
- PATCH: 0
- Pre-release: beta.2

Quality Score Impact: +5 points

Note: Pre-release versions indicate unstable releases.

Failure (Invalid Format):

❌ Semantic Versioning: FAIL

Version: 1.0
Format: Invalid
Valid: No

Issues Found:
1. Missing PATCH component
2. Expected format: MAJOR.MINOR.PATCH

Suggested Correction: 1.0.0

Quality Score Impact: 0 points (fix to gain +5)

Fix to comply with Semantic Versioning 2.0.0 specification.
Reference: https://semver.org/

Warning (Strict Mode):

⚠️  Semantic Versioning: WARNING

Version: 1.0.0-alpha.1
Format: Valid semver, but not strict
Valid: Yes (with pre-release)

Note: OpenPlugins recommends strict MAJOR.MINOR.PATCH format
without pre-release or build metadata for marketplace submissions.

Recommended: 1.0.0 (for stable release)

Quality Score Impact: +5 points (valid, but consider strict format)

Versioning Guidelines

When to increment:

MAJOR (X.0.0):

• Breaking API changes
• Incompatible changes
• Major rewrites

MINOR (x.Y.0):

• New features (backward-compatible)
• Deprecations
• Significant improvements

PATCH (x.y.Z):

• Bug fixes
• Security patches
• Minor improvements

Initial Development:

• Start with 0.1.0
• Increment MINOR for features
• First stable release: 1.0.0

Pre-release Identifiers:

• alpha - Early testing
• beta - Feature complete, testing
• rc - Release candidate

Compliance Criteria

PASS Requirements:

• Three numeric components (MAJOR.MINOR.PATCH)
• Each component is non-negative integer
• Components separated by dots
• Optional pre-release identifier (hyphen-separated)
• Optional build metadata (plus-separated)
• No leading zeros (except single 0)

FAIL Indicators:

• Missing components (1.0)
• Too many components (1.0.0.0)
• Non-numeric components (1.x.0)
• Leading 'v' prefix
• Invalid separators
• Leading zeros (01.02.03)

Request: $ARGUMENTS