How should I organise my version 2 and version 3 code?

Effective organization of successive software versions—specifically transitioning from Version 2 (v2) to Version 3 (v3)—requires a distinction between version control (tracking history) and architectural versioning (supporting multiple active iterations). The choice of organization depends on whether the goal is internal migration or public-facing API stability. ## Structural Approaches to Versioning There are three primary methodologies for organizing distinct versions within a codebase: 1. **Namespace and Directory Isolation** In monolithic or modular systems, v2 and v3 are often maintained in parallel within the same repository using directory-level separation (e.g., `src/v2/` and `src/v3/`). This approach allows shared utilities to remain in a common directory while distinct business logic or API schemas are isolated. It is the preferred method for internal transitions where both versions must coexist to support legacy clients during a migration period. 2. **Branch-Based Segregation** Utilizing Git branches (e.g., a `release/v2` branch and a `main` branch for v3) is standard for software that is distributed as a package or binary. This isolates the development environments entirely. However, this creates a maintenance burden, as critical bug fixes must be backported from the newer version to the older one through "cherry-picking" or manual integration. 3. **Service-Oriented Decoupling** In microservices architectures, v2 and v3 are treated as independent deployments. The organization happens at the infrastructure level, often managed by an API Gateway or a reverse proxy that routes traffic based on header information or URL paths (e.g., `api.example.com/v2`). This allows v3 to use an entirely different technology stack or database schema without impacting the stability of v2. ## Implementation Principles When organizing these versions, adhere to **Semantic Versioning (SemVer)**. A jump from v2 to v3 implies a breaking change, meaning the public interface is no longer backward compatible. To manage this transition cleanly: - **Dependency Inversion:** Use interfaces to abstract the core logic. Both v2 and v3 controllers can then implement the same underlying service interfaces where logic remains identical. - **The Strangler Fig Pattern:** Gradually migrate functionality from v2 to v3 by replacing specific components one by one until the v2 implementation is entirely "strangled" and can be decommissioned. - **Data Compatibility:** If v2 and v3 share a database, use a "Expand and Contract" pattern for schema changes to ensure that the new version does not break the data expectations of the old version. ## Directions for Further Exploration 1. **Schema Evolution:** How can database migrations be managed when v2 and v3 require different data structures but must operate on the same production data set? 2. **Deprecation Policies:** What are the industry standards for defining "End of Life" (EOL) for software versions to ensure a predictable sunsetting process for users? 3. **Automated Compatibility Testing:** How can contract testing be utilized to ensure that v3 does not inadvertently break legacy integrations relied upon by v2 clients?