feat: implement server versioning approach with semantic versioning support #296

domdomegg · 2025-08-22T01:45:07Z

This implements the versioning approach agreed upon in issue #158:

Key Changes

Documentation

Added comprehensive versioning guide (docs/versioning.md)
Updated FAQ with versioning guidance and best practices
Enhanced schema description with SHOULD recommendations

Schema Updates

Added 255-character limit for version strings in schema.json
Enhanced version field description with semantic versioning guidance

Implementation

New isSemanticVersion() function for proper semver detection
Enhanced compareSemanticVersions() with prerelease support
Implemented compareVersions() strategy:
- Both semver: use semantic comparison
- Neither semver: use timestamp comparison
- Mixed: semver versions always take precedence
Updated publish logic to determine "latest" using new strategy
Added version length validation (255 char max)

Versioning Strategy

Version MUST be string up to 255 characters
SHOULD use semantic versioning for predictable ordering
SHOULD align with package versions to reduce confusion
MAY use prerelease labels for registry-specific versions
Registry attempts semver parsing, falls back to timestamp ordering
Clients SHOULD follow same comparison logic

Resolves #158

Generated with Claude Code

…upport This implements the versioning approach agreed upon in issue #158: ## Key Changes ### Documentation - Added comprehensive versioning guide (docs/versioning.md) - Updated FAQ with versioning guidance and best practices - Enhanced schema description with SHOULD recommendations ### Schema Updates - Added 255-character limit for version strings in schema.json - Enhanced version field description with semantic versioning guidance ### Implementation - New isSemanticVersion() function for proper semver detection - Enhanced compareSemanticVersions() with prerelease support - Implemented compareVersions() strategy: * Both semver: use semantic comparison * Neither semver: use timestamp comparison * Mixed: semver versions always take precedence - Updated publish logic to determine "latest" using new strategy - Added version length validation (255 char max) ### Versioning Strategy 1. Version MUST be string up to 255 characters 2. SHOULD use semantic versioning for predictable ordering 3. SHOULD align with package versions to reduce confusion 4. MAY use prerelease labels for registry-specific versions 5. Registry attempts semver parsing, falls back to timestamp ordering 6. Clients SHOULD follow same comparison logic Resolves #158 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: adam jones <domdomegg@users.noreply.github.com>

domdomegg · 2025-08-22T01:45:43Z

@claude I think the logic for ordering etc. shouldn't happen in database/memory.go - it should happen a layer higher at the service layer, not persistence layer.

claude · 2025-08-22T01:45:58Z

Claude finished @domdomegg's task —— View job

Successfully moved version ordering logic from database layer to service layer! ✅

Tasks Completed:

Analyze current versioning implementation in internal/database/memory.go
Examine service layer structure in internal/service/
Move version comparison logic to service layer
Update database layer to use service layer methods
Update any other references to the moved functions
Run linting and tests
Commit and push changes

Summary

Successfully refactored the version ordering logic as requested:

✅ Created internal/service/versioning.go with exported functions:

IsSemanticVersion() - checks if version follows semver format
CompareSemanticVersions() - compares two semver strings
CompareVersions() - implements the full versioning strategy

✅ Updated internal/service/registry_service.go:

Service layer now handles version comparison business logic in Publish() method
Added helper methods for getting existing versions and determining latest status

✅ Simplified internal/database/memory.go:

Removed version comparison functions (moved to service layer)
Simplified Publish() method to only handle persistence
Cleaned up unused imports

✅ All tests pass - No breaking changes to existing functionality

The architecture now properly separates concerns:

Service layer: Business logic (version comparison, determining latest)
Database layer: Pure persistence (storage, retrieval, constraints)

- Move isSemanticVersion, compareSemanticVersions, and compareVersions functions from internal/database/memory.go to new internal/service/versioning.go - Update service layer to handle version comparison business logic - Simplify database layer to only handle persistence - All tests pass, maintaining existing functionality Co-authored-by: adam jones <domdomegg@users.noreply.github.com>

domdomegg · 2025-08-22T02:54:20Z

docs/versioning.md

+
+### For Non-Semantic Versions
+If version parsing as semantic version fails:
+- The registry will always mark the version as latest (overriding any previous version)


This feels reasonable in isolation. but actually means that version's total ordering is inconsistent with is_latest, for packages with a mix of versions.

Not sure what is best to do here. Maybe this is fine. Maybe we should only update is_latest if it's now the latest in the total ordering spec below, idk.

I think this behavior is necessary because the publisher does not indicate whether they are actually using semantic versioning. For example, if we said "semantic versions always take precedence", and a publisher is using non-semantic version numbers that sometimes appear to be semantic, then they are going to have a bad time. 😆

Unfortunately, as you noted, this means there is no natural sort order. Instead, we have to maintain an insertion order based on this logic.

domdomegg · 2025-08-22T02:54:46Z

docs/versioning.md

+```json
+{
+  "version_detail": {
+    "version": "1.2.3-gke.1"


Suggested change

"version": "1.2.3-gke.1"

"version": "1.2.3-1"

domdomegg · 2025-08-22T02:57:32Z

internal/service/registry_service.go

+// getVersionsByName retrieves all versions of a server by name
+func (s *registryServiceImpl) getVersionsByName(ctx context.Context, name string) ([]*model.ServerDetail, error) {
+	// Use the database's List method to find all servers with the same name
+	entries, _, err := s.db.List(ctx, map[string]any{"name": name}, "", 1000) // Large limit to get all versions


fixed limit may cause problems, although no limit may cause dos. think this is okay for now.

domdomegg · 2025-08-22T02:58:03Z

internal/service/versioning.go

@@ -0,0 +1,125 @@
+package service


should have unit tests

jonathanhefner · 2025-08-22T17:19:01Z

docs/versioning.md

+
+### For Non-Semantic Versions
+If version parsing as semantic version fails:
+- The registry will always mark the version as latest (overriding any previous version)


I think this behavior is necessary because the publisher does not indicate whether they are actually using semantic versioning. For example, if we said "semantic versions always take precedence", and a publisher is using non-semantic version numbers that sometimes appear to be semantic, then they are going to have a bad time. 😆

Unfortunately, as you noted, this means there is no natural sort order. Instead, we have to maintain an insertion order based on this logic.

jonathanhefner · 2025-08-22T17:21:16Z

docs/versioning.md

+When comparing versions where one is semantic and one is not:
+- The semantic version is always considered higher
+- This ensures semantic versions take precedence in ordering


I think this conflicts with the above section ("If version parsing as semantic version fails"), and I think it may potentially result in undesirable behavior (see my comment on the above section).

jonathanhefner · 2025-08-22T17:22:33Z

docs/versioning.md

+## Examples
+
+### Valid Semantic Versions
+```json


Suggested change

```json

```javascript

jonathanhefner · 2025-08-22T17:22:40Z

docs/versioning.md

+```
+
+### Non-Semantic Versions (Allowed)
+```json


Suggested change

```json

```javascript

domdomegg commented Aug 22, 2025

View reviewed changes

internal/service/versioning.go

@@ -0,0 +1,125 @@

package service

Copy link

Member Author

domdomegg Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should have unit tests

domdomegg marked this pull request as ready for review August 22, 2025 02:58

jonathanhefner reviewed Aug 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: implement server versioning approach with semantic versioning support #296

feat: implement server versioning approach with semantic versioning support #296

Uh oh!

domdomegg commented Aug 22, 2025

Uh oh!

domdomegg commented Aug 22, 2025

Uh oh!

claude bot commented Aug 22, 2025 •

edited

Loading

Uh oh!

domdomegg Aug 22, 2025

Uh oh!

jonathanhefner Aug 22, 2025

Uh oh!

domdomegg Aug 22, 2025

Uh oh!

domdomegg Aug 22, 2025

Uh oh!

domdomegg Aug 22, 2025

Uh oh!

jonathanhefner Aug 22, 2025

Uh oh!

jonathanhefner Aug 22, 2025

Uh oh!

jonathanhefner Aug 22, 2025

Uh oh!

jonathanhefner Aug 22, 2025

Uh oh!

Uh oh!

feat: implement server versioning approach with semantic versioning support #296

Are you sure you want to change the base?

feat: implement server versioning approach with semantic versioning support #296

Uh oh!

Conversation

domdomegg commented Aug 22, 2025

Key Changes

Documentation

Schema Updates

Implementation

Versioning Strategy

Uh oh!

domdomegg commented Aug 22, 2025

Uh oh!

claude bot commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tasks Completed:

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

claude bot commented Aug 22, 2025 •

edited

Loading