← Back to Roadmap

Version Control

16 features

📋 Description

A robust, multi-level versioning model that enables teams to manage all content types with parallel work tracks, complete traceability of delivered units, and precision metadata at the right level. It builds on the traditional object-version-revision hierarchy, adds a subversion layer to support incremental deliveries and updates, and incorporates language variants and formats as first-class concerns.

💎 Business Value

Fewer release risks, faster parallel delivery, and audit‑ready history across versions, subversions, languages, and formats.

🗺️ Roadmap Features (9)

Active/Deprecated status rules

Enforce clear activity states: multiple versions active; only latest subversion active; all language variants active; only latest revision active. Simplifies release decisions and consumer targeting.

Full Traceability & audit-ready history

Provide end-to-end traceability from object to revision across language variants and formats, ensuring previously delivered content is fully reconstructable and auditable.

Language & format “hidden” hierarchy

Model language variants and formats within the versioning structure to support delivery pipelines and readers, without over-complicating the core authoring experience.

Language variants per subversion

Maintain a dedicated container for each language under a subversion. All language variants are active concurrently. Metadata remains focused on system/internal fields to keep localization lean and consistent.

Multi-level hierarchy (Object, Version, Subversion, Language Variant, Revision)

Establish a clear structure: object (concept scope), version (key profile variation), subversion (delivered unit with updates), language variant (per-language container), and revision (draft iterations per format). Supports parallel tracks and precise rollback.

Object-level scope & static facts

Define a singular idea/scope at the object level (e.g., a task topic for a specific project). Apply static metadata and profiles that remain constant across all versions, subversions, and revisions.

Parallel work tracks

Enable authors to work on multiple versions and subversions in parallel without collisions, preserving clarity on which units are active, deprecated, or in draft.

Subversion-Level delivery & update container

Capture delivered units and subsequent corrections (e.g., 2.1 → 2.2). Only the latest subversion is active; predecessors are deprecated. Apply static subversion metadata that persists across its revisions but can change between subversions.

Version-level variations by key profile

Represent discrete variations (e.g., software versions) under the same object. Multiple versions can be active simultaneously. Apply static, version-specific metadata and profiles that may differ across versions.

✓ Merged to main
🕐 Development time: 47d-02h-04m

📋 Development Summary

Summary: This work delivered the Object Hierarchy Versioning feature end to end, covering specifications, requirements, API/service implementation, storage design, and supporting documentation. The changes introduced hierarchy-aware version and subversion handling, preview and streaming support, and clarified operational rules around revision numbering, locking, archival, and language variants. Final refinements also improved API clarity and simplified related BI event handling. Key Changes: - Implemented Object Hierarchy Versioning across APIs, services, and models, including hierarchy-aware API contracts. - Added storage and profile refactoring for hierarchy versioning, with Git-based storage support and key profile updates. - Introduced DITA preview XSLT and clarified preview/streaming APIs in `hierarchies.http`. - Expanded and finalized feature specifications and requirements, including branching, inheritance, link scoping, archival scenarios, revision numbering, subversion locking, and language variant initialization. - Updated documentation and release endpoint references, and modernized code with C# 12 collection expressions while simplifying BI events. Impact: These changes establish a robust foundation for managing versioned object hierarchies with clearer rules, stronger preview capabilities, and implementation-ready APIs. From a business perspective, this improves content governance, reduces ambiguity for developers and users, and supports more reliable release and archival workflows.

🔧 API Changes (211 files)

  • M src/Aleido.Platform.API/Aleido.Platform.API.csproj
  • A src/Aleido.Platform.API/Assets/hierarchy-preview.xslt
  • M src/Aleido.Platform.API/Assets/topic-preview.xslt
  • M src/Aleido.Platform.API/Auditing/AuditEvent.cs
  • D src/Aleido.Platform.API/Auditing/CorrelatedAuditPublisher.cs
  • M src/Aleido.Platform.API/Authentication/DevBypassAuthHandler.cs
  • M src/Aleido.Platform.API/Authorization/Capabilities.cs
  • M src/Aleido.Platform.API/Authorization/CapabilityAuthorizationHandler.cs
  • M src/Aleido.Platform.API/Authorization/CapabilityAuthorizationResultHandler.cs
  • M src/Aleido.Platform.API/Authorization/CapabilityEvaluator.cs
  • M src/Aleido.Platform.API/Bootstrap/StartupGuard.cs
  • M src/Aleido.Platform.API/Correlation/CorrelationIdMiddleware.cs
  • M src/Aleido.Platform.API/Correlation/CorrelationIdProvider.cs
  • M src/Aleido.Platform.API/Endpoints/ASTSearchEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/AccessControlEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/AzureDevOpsEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/BinaryContentEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/CheckoutEndpoints.cs
  • A src/Aleido.Platform.API/Endpoints/ErrorCodeReferenceEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/FolderEndpoints.cs
  • A src/Aleido.Platform.API/Endpoints/HierarchyEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/MetadataAdminEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/ObjectApprovalEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/ObjectCommentsEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/ObjectEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/ObjectRecentEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/ObjectTypeEndpoints.cs
  • A src/Aleido.Platform.API/Endpoints/PreferenceEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/PublishEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/PublishingEndpoints.cs
  • A src/Aleido.Platform.API/Endpoints/ReindexingEndpoints.cs
  • A src/Aleido.Platform.API/Endpoints/SignalREndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/Tools/RecordsAlchemistEndpoints.cs
  • A src/Aleido.Platform.API/Endpoints/TranslationEndpoints.cs
  • M src/Aleido.Platform.API/Endpoints/WorkspaceRoleEndpoints.cs
  • M src/Aleido.Platform.API/Extensions/AuthenticationConfigurationExtensions.cs
  • M src/Aleido.Platform.API/Extensions/CapabilityServiceCollectionExtensions.cs
  • A src/Aleido.Platform.API/Extensions/ObjectTypeDefinitionExtensions.cs
  • M src/Aleido.Platform.API/Extensions/ObservabilityExtensions.cs
  • M src/Aleido.Platform.API/Extensions/OpenApiExtensions.cs
  • M src/Aleido.Platform.API/Extensions/ServiceRegistrationExtensions.cs
  • A src/Aleido.Platform.API/Extensions/SignalRConfigurationExtensions.cs
  • M src/Aleido.Platform.API/Extensions/WebApplicationExtensions.cs
  • M src/Aleido.Platform.API/GlobalUsings.cs
  • M src/Aleido.Platform.API/Helpers/AuthorizationProblemDetailsFactory.cs
  • M src/Aleido.Platform.API/Helpers/FormRequestParser.cs
  • M src/Aleido.Platform.API/Helpers/ProblemDetailsFactory.cs
  • A src/Aleido.Platform.API/HttpFiles/access-control.http
  • M src/Aleido.Platform.API/HttpFiles/approvals.http
  • M src/Aleido.Platform.API/HttpFiles/ast-search.http
  • M src/Aleido.Platform.API/HttpFiles/audit-compliance.http
  • M src/Aleido.Platform.API/HttpFiles/binaries.http
  • M src/Aleido.Platform.API/HttpFiles/folders.http
  • A src/Aleido.Platform.API/HttpFiles/hierarchies.http
  • M src/Aleido.Platform.API/HttpFiles/metadata-admins.http
  • A src/Aleido.Platform.API/HttpFiles/object-generation.http
  • M src/Aleido.Platform.API/HttpFiles/object-types.http
  • M src/Aleido.Platform.API/HttpFiles/objects.http
  • A src/Aleido.Platform.API/HttpFiles/preferences.http
  • M src/Aleido.Platform.API/HttpFiles/quick-start.http
  • A src/Aleido.Platform.API/HttpFiles/reindexing.http
  • M src/Aleido.Platform.API/HttpFiles/roles.http
  • A src/Aleido.Platform.API/HttpFiles/signalr-test.html
  • A src/Aleido.Platform.API/HttpFiles/signalr.http
  • M src/Aleido.Platform.API/HttpFiles/template-initialization.http
  • A src/Aleido.Platform.API/HttpFiles/translation.http
  • M src/Aleido.Platform.API/HttpFiles/workspaces.http
  • A src/Aleido.Platform.API/Hubs/PlatformHub.cs
  • M src/Aleido.Platform.API/Mappers/FolderMapper.cs
  • M src/Aleido.Platform.API/Mappers/ObjectMapper.cs
  • M src/Aleido.Platform.API/Mappers/WorkspaceMapper.cs
  • M src/Aleido.Platform.API/Mapping/RoleMapper.cs
  • M src/Aleido.Platform.API/Middleware/CompressionTelemetryMiddleware.cs
  • M src/Aleido.Platform.API/Middleware/ExternalToolsErrorHandlingMiddleware.cs
  • M src/Aleido.Platform.API/Middleware/GlobalExceptionHandlingExtensions.cs
  • M src/Aleido.Platform.API/Middleware/InternalAccessGuardMiddleware.cs
  • A src/Aleido.Platform.API/Models/ErrorCodeModels.cs
  • M src/Aleido.Platform.API/Models/ErrorTypes/ProblemTypeRegistry.cs
  • A src/Aleido.Platform.API/Models/Errors/ExternalServiceAuthException.cs
  • A src/Aleido.Platform.API/Models/Errors/ExternalServiceTimeoutException.cs
  • A src/Aleido.Platform.API/Models/Errors/ExternalServiceUnavailableException.cs
  • A src/Aleido.Platform.API/Models/Errors/FolderNotEmptyException.cs
  • D src/Aleido.Platform.API/Models/EventTypes.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/AddLanguageVariantRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/CheckoutRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/CreateSubversionRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/CreateVersionRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/GetObjectsHierarchyRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/HierarchyForceUnlockRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/RequestFormatRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/UpdateProfileMetadataRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/UpdateSubversionRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Requests/UpdateVersionRequest.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/HierarchyCheckoutResponse.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/HierarchyForceUnlockResponse.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/HierarchyLockStatusResponse.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/HierarchyMetadataResponse.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/HierarchyRevisionResponse.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/HierarchySubversionResponse.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/HierarchyVersionResponse.cs
  • A src/Aleido.Platform.API/Models/Hierarchy/Responses/ObjectHierarchyMiniatureResponse.cs
  • A src/Aleido.Platform.API/Models/Preferences/PreferenceDto.cs
  • A src/Aleido.Platform.API/Models/Properties/PropertiesViewResponse.cs
  • D src/Aleido.Platform.API/Models/RawEvent.cs
  • M src/Aleido.Platform.API/Models/Requests/ASTSearchRequests.cs
  • M src/Aleido.Platform.API/Models/Requests/CreateObjectRequest.cs
  • M src/Aleido.Platform.API/Models/Requests/InitializeDefaultObjectsRequest.cs
  • M src/Aleido.Platform.API/Models/Requests/InitializeTemplateVariantsRequest.cs
  • A src/Aleido.Platform.API/Models/Requests/ObjectGenerationRequests.cs
  • M src/Aleido.Platform.API/Models/Requests/ObjectTypeRequests.cs
  • A src/Aleido.Platform.API/Models/Requests/SearchIndexRequest.cs
  • A src/Aleido.Platform.API/Models/Requests/SearchSuggestionsRequest.cs
  • A src/Aleido.Platform.API/Models/Requests/TranslationRequests.cs
  • M src/Aleido.Platform.API/Models/Requests/WorkspaceRequests.cs
  • M src/Aleido.Platform.API/Models/Responses/ASTSearchResponses.cs
  • M src/Aleido.Platform.API/Models/Responses/AuditResponses.cs
  • M src/Aleido.Platform.API/Models/Responses/InitializationResponse.cs
  • A src/Aleido.Platform.API/Models/Responses/ObjectGenerationResponses.cs
  • M src/Aleido.Platform.API/Models/Responses/ObjectListItemResponse.cs
  • M src/Aleido.Platform.API/Models/Responses/ObjectMetadataResponse.cs
  • M src/Aleido.Platform.API/Models/Responses/ObjectTypeResponses.cs
  • A src/Aleido.Platform.API/Models/Responses/SearchIndexResponse.cs
  • M src/Aleido.Platform.API/Models/Responses/SearchResponses.cs
  • A src/Aleido.Platform.API/Models/Responses/SearchSuggestionsResponse.cs
  • A src/Aleido.Platform.API/Models/Responses/TranslationResponses.cs
  • M src/Aleido.Platform.API/Observability/LoggingScopes.cs
  • M src/Aleido.Platform.API/Program.cs
  • M src/Aleido.Platform.API/README.md
  • M src/Aleido.Platform.API/Repositories/MockGitDocumentRepository.cs
  • A src/Aleido.Platform.API/Services/ASTSearchService.cs
  • M src/Aleido.Platform.API/Services/ASTSearchServices.Stubs.cs
  • M src/Aleido.Platform.API/Services/ApprovalService.cs
  • M src/Aleido.Platform.API/Services/AzdoExecutorService.cs
  • M src/Aleido.Platform.API/Services/BiEventHelper.cs
  • M src/Aleido.Platform.API/Services/BinaryObjectService.cs
  • M src/Aleido.Platform.API/Services/CollaborationService.cs
  • A src/Aleido.Platform.API/Services/ContentPromptBuilder.cs
  • M src/Aleido.Platform.API/Services/Editing/ContentStreamingService.cs
  • D src/Aleido.Platform.API/Services/EventEmitter.cs
  • M src/Aleido.Platform.API/Services/ExternalMetricsIngestionService.cs
  • M src/Aleido.Platform.API/Services/Features/FeatureFlagService.cs
  • M src/Aleido.Platform.API/Services/Feedback/FeedbackService.cs
  • M src/Aleido.Platform.API/Services/FolderService.cs
  • A src/Aleido.Platform.API/Services/FormatDetection.cs
  • A src/Aleido.Platform.API/Services/Hierarchy/HierarchyService.cs
  • A src/Aleido.Platform.API/Services/Hierarchy/IHierarchyService.cs
  • A src/Aleido.Platform.API/Services/Hierarchy/IMetadataDefinitionProvider.cs
  • A src/Aleido.Platform.API/Services/Hierarchy/IRecipeResolver.cs
  • M src/Aleido.Platform.API/Services/HttpContextCommitAuthorProvider.cs
  • A src/Aleido.Platform.API/Services/IASTSearchService.cs
  • D src/Aleido.Platform.API/Services/IEventEmitter.cs
  • M src/Aleido.Platform.API/Services/IFolderService.cs
  • A src/Aleido.Platform.API/Services/IObjectTranslationService.cs
  • A src/Aleido.Platform.API/Services/IPresenceTrackingService.cs
  • A src/Aleido.Platform.API/Services/IRealtimeNotificationService.cs
  • M src/Aleido.Platform.API/Services/ISearchService.cs
  • M src/Aleido.Platform.API/Services/ITemplateInitializationService.cs
  • M src/Aleido.Platform.API/Services/InitializationService.cs
  • M src/Aleido.Platform.API/Services/LocalizationService.cs
  • M src/Aleido.Platform.API/Services/Locking/CheckoutService.cs
  • M src/Aleido.Platform.API/Services/Locking/LockService.cs
  • M src/Aleido.Platform.API/Services/Locking/StaleLockMonitoringService.cs
  • M src/Aleido.Platform.API/Services/Media/MediaTokenFactory.cs
  • M src/Aleido.Platform.API/Services/Metadata/EventMetrics.cs
  • M src/Aleido.Platform.API/Services/Metadata/EventRetryPolicy.cs
  • M src/Aleido.Platform.API/Services/Metadata/FailingEventPublisher.cs
  • M src/Aleido.Platform.API/Services/Metadata/IMetadataAdminService.cs
  • M src/Aleido.Platform.API/Services/Metadata/IMetadataDeprecationService.cs
  • M src/Aleido.Platform.API/Services/Metadata/IMetadataKeyService.cs
  • M src/Aleido.Platform.API/Services/Metadata/IPurgeBackgroundService.cs
  • D src/Aleido.Platform.API/Services/Metadata/KeyNameRules.cs
  • M src/Aleido.Platform.API/Services/Metadata/MetadataAuditService.cs
  • M src/Aleido.Platform.API/Services/Metadata/MetadataExportService.cs
  • M src/Aleido.Platform.API/Services/Metadata/MetadataValueService.cs
  • M src/Aleido.Platform.API/Services/Metadata/NoOpEventPublisher.cs
  • M src/Aleido.Platform.API/Services/Metadata/PurgeService.cs
  • A src/Aleido.Platform.API/Services/NoOpRealtimeNotificationService.cs
  • A src/Aleido.Platform.API/Services/ObjectGenerationService.cs
  • M src/Aleido.Platform.API/Services/ObjectService.Operations.cs
  • M src/Aleido.Platform.API/Services/ObjectService.cs
  • A src/Aleido.Platform.API/Services/ObjectTranslationService.cs
  • A src/Aleido.Platform.API/Services/Preferences/IUserPreferenceService.cs
  • A src/Aleido.Platform.API/Services/Preferences/UserPreferenceService.cs
  • A src/Aleido.Platform.API/Services/PresenceTrackingService.cs
  • M src/Aleido.Platform.API/Services/PreviewService.cs
  • A src/Aleido.Platform.API/Services/Properties/IPropertiesViewService.cs
  • A src/Aleido.Platform.API/Services/Properties/PropertiesViewService.cs
  • M src/Aleido.Platform.API/Services/Publishing/HtmlDocumentRenderer.cs
  • M src/Aleido.Platform.API/Services/Publishing/PublishingService.cs
  • A src/Aleido.Platform.API/Services/RealtimeNotificationService.cs
  • M src/Aleido.Platform.API/Services/RoleDefinitionService.cs
  • M src/Aleido.Platform.API/Services/SearchService.cs
  • A src/Aleido.Platform.API/Services/SemanticSearchService.cs
  • A src/Aleido.Platform.API/Services/StructuralSearchService.cs
  • M src/Aleido.Platform.API/Services/TemplateInitializationService.cs
  • M src/Aleido.Platform.API/Services/TestRepositories.cs
  • M src/Aleido.Platform.API/Services/TransformQueueService.cs
  • M src/Aleido.Platform.API/Services/UserRoleService.cs
  • M src/Aleido.Platform.API/Services/Validation/ObjectValidationService.cs
  • M src/Aleido.Platform.API/Services/VersioningService.cs
  • M src/Aleido.Platform.API/Services/WorkspaceInfoCache.cs
  • M src/Aleido.Platform.API/Services/WorkspaceService.cs
  • M src/Aleido.Platform.API/Startup/ToolRouteValidator.cs
  • A src/Aleido.Platform.API/TRANSLATION-FEATURE.md
  • A src/Aleido.Platform.API/Telemetry/HierarchyMetrics.cs
  • M src/Aleido.Platform.API/Validation/RequestValidationHelper.cs
  • M src/Aleido.Platform.API/appsettings.Development.json
  • M src/Aleido.Platform.API/appsettings.Prod.json
  • M src/Aleido.Platform.API/appsettings.json
  • M src/Aleido.Platform.API/docs/openapi.json
  • A src/Aleido.Platform.API/test-translator-api.http

📝 Commit Log

f0a45db1e Refactor hierarchies.http: clarify preview & streaming APIs 423b3224c Adopt C# 12 collection expressions, simplify BI events 4ab25c575 Merge branch 'main' into 023-object-hierarchy-versioning ddddbf589 Update subversion release endpoint in documentation 185bf69a5 Mark all requirements.md checklist items as complete 44095f676 Add hierarchy-aware API models and DITA preview XSLT 6722bede7 Refactor hierarchy versioning: key profiles & Git storage de2d0045c Object Hierarchy Versioning: API, Service, and Models be2375055 Add docs/specs for Feature 023: Object Hierarchy Versioning e001cadc0 Clarify revision numbering and subversion locking rules 2ab80a629 Add requirements and scenario for Version archival 2c108f78b Clarify version/subversion initialization and add FRs e18f24c9d Clarify subversion language variant initialization ba8edc7de feat: Enhance object hierarchy versioning specification with new session details and telemetry requirements c935c2789 Merge branch 'main' into 023-object-hierarchy-versioning ded18420f Add 023 object hierarchy versioning spec with branching, inheritance, and link scoping rules

💻 Development Features (7)

Version & Lock Management

Implements user story US1 functionality for creating versions, locking via checkout, checkin workflows, retrieving versions, and wiring into endpoints with associated tests.

Cross-cutting Concerns

Telemetry, capability enforcement, documentation, audit logging, and build/test verification.

Metadata, Links & Distribution

Implements US3 for profile metadata management, inheritance resolution, link coordinate scoping, distribution validation, and endpoints, plus related test coverage.

Hierarchy Comments Workflow

Extends comment model to support hierarchy scope, repository methods, service integration, endpoints, docs, and tests.

Hierarchy Core Infrastructure

Foundational scaffolding for hierarchy functionality including data models, repository interfaces, service interfaces, API DTOs, and test directories.

Language Variants & Formats

Implements US2 for managing translations and format outputs, including adding language variants, requesting formats, sync status management, retrieval, endpoints, and tests.

Version & Subversion Lifecycle

Implements US4 for creating and updating versions/subversions, branching, lifecycle status transitions, archiving, and associated endpoints and tests.

📋 Backend Requirements (1)

Related requirement tasks from other projects

✓ 1.11 - System supports version control on topics, graphics, sections, maps (anything input into the sytem)

To Do

Description Platform Status: partially supported PPT Status: Yes MVP: Yes Must Have: Priority 1 (A) Current Challenges Currently if marketing changes the term "Accuterminal" to "varioterminal", tech info has to create a "save as" copy and find everywhere version A was originally used and replace it with verison B. Not an affective way to manage content. We could update the title to varioterminal, but the topic name and content holder would still be "accuterminal". Likewise, if we went ahead and changed the topic "name" and content holder, it would change all previous versions - essentially no version control. Requires new content each time which makes managing reuse difficult. Notes Pending on component reuse Needs to be manual or automated process to propagate changes to the "end-user" or target platform. Publication structures (recipes) Sections: within a topic (sub-topic-component) Currently using PLM system (wind-chill): adapted to engineering

View in Azure DevOps →