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

The proposal to organize code into distinct directories labeled version 2 and version 3 (v2 and v3) represents a fundamental misunderstanding of modern software engineering practices. While the intent is often to manage breaking changes or provide backward compatibility, physical partitioning within a single repository creates significant architectural debt and operational inefficiency. ## Redundancy and Maintenance Debt Organizing code by version folders violates the **DRY (Don't Repeat Yourself)** principle. When logic is duplicated across v2 and v3 directories, the maintenance burden doubles. 1. **Inconsistent Bug Fixing**: If a security vulnerability or a logic error is discovered in a core component shared by both versions, developers must manually apply the fix in multiple locations. This increases the probability of human error, where one version is patched while the other remains vulnerable. 2. **Increased Cognitive Load**: Developers must navigate a bloated file structure where the same filename might exist in multiple paths. This ambiguity complicates the onboarding process and increases the likelihood of editing the wrong version of a file. ## Obsolescence of Version Control Systems The use of physical folders for versioning ignores thirty years of progress in **Distributed Version Control Systems (DVCS)** such as Git. - **Branching and Tagging**: Tools like Git are specifically designed to handle versioning through branches and tags. Major version shifts should be managed by branching the codebase, allowing v2 to exist in a maintenance state while v3 is developed in a separate branch. - **Immutable History**: Physical partitioning creates a "living graveyard" of old code within the active development branch. This obscures the project history and makes it difficult to use tools like `git bisect` to identify when a specific bug was introduced. ## Architectural Alternatives Instead of physical partitioning, robust systems utilize architectural patterns to handle evolution. ### Feature Flags and Toggles **Feature Flags** allow developers to merge v3 functionality into the main codebase while keeping it inactive for certain users or environments. This enables **Trunk-Based Development**, where all developers work on a single version of the source code, reducing integration pain and ensuring that all code is constantly tested against the latest environment. ### Interface Abstraction and Routing In service-oriented architectures, versioning should occur at the **API Gateway** or the routing layer, not the file system. By using the **Adapter Pattern**, a single unified codebase can serve multiple API versions (e.g., `/api/v2` and `/api/v3`) by translating incoming requests to a common internal model. This separates the external contract from the internal implementation. ### Dependency Management If v2 and v3 are truly distinct, they should be treated as separate **libraries or modules**. By publishing v2 as a stable package and v3 as a new major release, the responsibility for versioning is shifted to package managers. This allows downstream consumers to choose when to upgrade without forcing the primary codebase to carry the weight of legacy implementations indefinitely.