ADR: Web Publishing of OmegaT Manual with Versioned Structure

Status

Accepted – Implemented

Context

OmegaT currently publishes online manuals using named release identifiers:

  • https://omegat.sourceforge.io/manual-standard/

  • https://omegat.sourceforge.io/manual-snapshot/

The OmegaT application includes built-in URLs that direct users to these online manuals. However, we have identified several issues with the current approach:

  1. Version inconsistency: Different OmegaT versions show mismatched manual versions (e.g., OmegaT 5.8 shows manual 5.7.1, OmegaT 6.1.0 Beta shows manual 5.7.1)

  2. Maintenance overhead: Managing “standard” and “snapshot” designations requires manual intervention

  3. User confusion: Users cannot easily identify which version of documentation they are viewing

Our release strategy has evolved to a single line of standard releases alongside snapshot/weekly development releases, but the documentation structure hasn’t adapted accordingly.

Decision

We will implement a versioned manual storage system with automated symbolic link management that maintains the existing URL structure for applications and support workflows.

Technical Implementation:

  1. Versioned Storage: Store each manual build in version-specific directories:

    • /manual/6.1.0/ (for standard releases)

    • /manual/6.1.0-snapshot/ (for snapshot releases)

  2. Automated Symbolic Links:

    • Build system automatically updates manual-standard symbolic link to point to the latest stable version

    • Build system automatically updates manual-snapshot symbolic link to point to the current development version

  3. Application URL Structure (Unchanged):

    • OmegaT applications continue linking to /manual-standard/ and /manual-snapshot/

    • Support team continues using existing standard/snapshot URLs

  4. Build Process Integration:

    • Standard release builds update the manual-standard symbolic link

    • Snapshot release builds update the manual-snapshot symbolic link

    • Version transitions (e.g., development → GA) automatically switch symbolic links

Consequences

Positive:

  • Version Consistency: Each OmegaT version will display documentation consistent with its release version

  • Zero Ongoing Maintenance: Symbolic link updates are fully automated through the build process

  • Backward Compatibility: Existing URLs and workflows remain unchanged

  • Support Workflow Preserved: Support team continues using standard/snapshot links

  • Historical Documentation: Previous versions remain accessible via versioned URLs

  • Automated Deployment: No manual intervention required for version transitions

Negative:

  • Increased Storage: Each version requires separate storage (mitigated by using symbolic links for active documentation)

  • Initial Setup Complexity: Requires one-time modification of build scripts

Neutral:

  • Same Documentation Maintenance: Continue maintaining only 2 active documentation sets (standard + snapshot)

  • Same Philosophical Approach: Packaged documentation remains canonical, online serves support purposes

Implementation Plan

  1. Phase 1: Modify build scripts to create versioned directories and manage symbolic links

  2. Phase 2: Deploy automated symbolic link management for both standard and snapshot builds

  3. Phase 3: Validate automatic version transitions work correctly

  4. Phase 4: Monitor and document the new process

Alternatives Considered

  1. Version-specific application URLs: Would require updating all OmegaT applications and break existing bookmarks

  2. Manual redirect management: Would require ongoing maintenance and manual .htaccess updates

  3. Status quo: Continues current version inconsistency and user confusion issues

References

Notes

This decision maintains the existing documentation philosophy (packaged documentation as canonical reference, online for support) while solving the technical inconsistency issues through automation.

The implementation leverages existing build infrastructure (Azure Pipelines, SourceForge hosting) with minimal modifications to achieve zero ongoing maintenance overhead.

  • Date: 2025-09-20

  • Updated: 2025-10-05

  • Author: Hiroshi Miura

  • Reviewers: OmegaT Development Team