Stop Copy‑Pasting: A Principles‑First Guide to Packages, Submodules, and Sustainable Code Reuse

You’ve noticed a pattern: you keep copying the same helpers, UI fragments, and backend glue into new repos. It works—until it doesn’t. The “fast” path spawns a garden of slightly different variants that all need to be updated, tested, and explained. You’re not alone. Most teams fall into this trap, and many stay there for years because the fix appears to be a tooling choice (“Should I use Git submodules?” “Should I publish a package?”) when the real solution is a way of thinking about reuse.

This lab is a conceptual deep dive (not a step‑by‑step tutorial) on the principles that create durable reuse. We’ll compare packages, submodules, subtrees, and monorepos; but the goal is clarity, not dogma. By the end, you should be able to answer:

• What should be extracted and why?
• Where should that code live?
• How does it evolve without breaking everything?
• How do I keep speed today while compounding quality tomorrow?

Why duplication hurts more than it seems

Copy‑pasting code creates forked histories. Each fork accumulates small local tweaks until the shared abstraction is unrecognizable across repos. The pain shows up as:

• Operational drag – the same bug must be fixed N times.
• Inconsistent behavior – tiny differences confuse users and future you.
• Blocked changes – a better design can’t roll out because you can’t touch every copy safely.
• Lost learning – fixes are not socialized; they die with the branch that needed them.

The question is not “How can I avoid duplication forever?” (you can’t) but rather “Where do I want change to flow?” You want change to flow through a single, visible channel where it can be tested, versioned, and reviewed once—then consumed everywhere.

Figure: Reuse decision hierarchy. The article's decision model starts before the strategy list: first identify consumers, then change flow, then API stability, then the operational contract.

{
  "type": "hierarchy",
  "title": "Reuse decision hierarchy",
  "caption": "This tree turns the article's practical lens into a decision structure. Reuse should become more managed only when audience, stability, and ownership demand it.",
  "hierarchy": {
    "name": "Candidate shared code",
    "children": [
      {
        "name": "Consumer pressure",
        "children": [
          { "name": "One consumer: stay local" },
          { "name": "2 consumers: document trigger" },
          { "name": "3+ consumers: evaluate extraction" }
        ]
      },
      {
        "name": "Change flow",
        "children": [
          { "name": "Lockstep: workspace / monorepo" },
          { "name": "Independent: package" },
          { "name": "Rare snapshot: submodule / subtree" }
        ]
      },
      {
        "name": "Contract maturity",
        "children": [
          { "name": "Tests" },
          { "name": "Public API" },
          { "name": "Version policy" },
          { "name": "Owner" }
        ]
      }
    ]
  }
}

The spectrum of reuse strategies (from least to most managed)

1) Vendoring / copy‑paste (ad hoc)

Fastest to start, slowest to maintain. Fine for throwaway experiments. Dangerous as a default.

Use sparingly: true spikes; code you will delete within days.

2) Git Submodules

A submodule pins a repo inside another repo at a specific commit. Think of it as “git dependencies.”

Strengths

• Clear separation of history and permissions.
• Consumers can pin to a known commit—great for regulated or long‑lived products.
• Works with any language/ecosystem.

Trade‑offs

• Operational friction: updating and syncing submodules is not intuitive.
• Tooling UX varies; many devs avoid them.
• Harder to test cross‑repo changes atomically without extra process.

When it shines: embedding a large, independent project (docs site, assets, firmware, legal content) where you need strict pinning and rare updates.

3) Git Subtree

Subtree merges one repo’s content into another while keeping the ability to sync changes in both directions.

Strengths

• No special checkout state; feels like normal files.
• Version pinning possible via merge commits.
• Good for pulling in code that changes occasionally but should live elsewhere.

Trade‑offs

• History becomes heavier; sync is manual discipline.
• Still not a “package contract” in the language ecosystem sense.

When it shines: sharing a small foundation repo across a handful of projects where tooling for packages is overkill.

4) Packages (language‑native distribution)

Publishable artifacts versioned in the ecosystem (npm, PyPI, Maven, etc.). This is the gold standard for APIs with consumers.

Strengths

• Contracts by default: semantic versions encode compatibility.
• Easy to consume, lock, and audit.
• Enables CI, changelogs, and deprecation flows.
• Works great for UI kits, utilities, data clients, SDKs.

Trade‑offs

• Up‑front design of public API surface.
• Release discipline (changelogs, version bumps).
• Private distribution adds auth and registry concerns.

When it shines: anything multiple codebases rely on and that benefits from stable interfaces—design systems, core utilities, auth modules, data clients, event schemas.

5) Monorepo + internal packages

A single repo hosting multiple packages/services with shared tooling. Popular in JS/TS with workspaces.

Strengths

• Atomic commits across packages; easy to refactor sweeping changes.
• Shared lint/test/build infra (“paved roads”).
• Local developer experience is ergonomic.

Trade‑offs

• Repo size and CI complexity need care.
• Access control is coarser (though code owners help).
• Requires cultural discipline to respect package boundaries inside the same repo.

When it shines: teams building a platform with many small libraries and apps that should evolve in lockstep—while still publishing versioned artifacts to consumers.

Principles that outlive tools

1) Design for change flow

Ask: Where will this code change most? Who needs those changes?

• Volatile utilities belong in a monorepo/internal package to refactor quickly.
• Stable, broadly useful APIs belong in versioned packages to protect consumers from churn.
• Heavy, rare dependencies can live as submodules or subtrees to pin and forget.

2) Name and narrow the surface

A good reusable unit has a clear promise (what it does) and narrow IO (what it needs/provides). The narrower the surface, the easier it is to change internals without breaking consumers.

• Prefer functions and adapters over global singletons.
• Prefer composition over inheritance.
• Keep configuration explicit (don’t read process env inside a generic library; accept a config object).

3) Treat tests as contracts

For a reusable unit, tests are not only correctness; they are documentation of the contract.

• Write black‑box tests that exercise public API only.
• Add example‑style tests that read like snippets from docs.
• Use snapshot tests carefully; prefer semantic assertions.

4) Semantic versioning is a promise

• MAJOR: break consumers only with intent and migration notes.
• MINOR: add features safely.
• PATCH: fix without surprises.

The point is not pedantry; it’s predictability for everyone pulling the code.

5) Prefer “paved paths” over freedom

Codify defaults: linting, formatting, release script, test runner, folder layout. Reuse is social; the easiest path wins.

6) Avoid hidden coupling

A package that silently reaches into your environment (global state, process, DOM) is hard to reuse. Every implicit dependency is an invisible wire you’ll trip over later.

What should become a package? A practical lens

Ask three questions:

1. Repeatability – Does this show up in 3+ projects? (Two is a coincidence; three is a pattern.)
2. Stability – Is the behavior well understood so we can commit to an API?
3. Audience – Who depends on it? Just you, or other teams/clients? The broader the audience, the more it benefits from packages and versioning.

Great candidates

• Design tokens + UI primitives (buttons, typography, layout utilities).
• Cross‑cutting utilities (date, money, validation, logging, feature flags).
• Data clients/SDKs (wrapping fetch/sql/redis/kafka with consistent error handling).
• Schema packages (types, zod/JSON schemas) shared by server and client.

Weak candidates

• High‑velocity features still in discovery.
• App‑specific glue (routing quirks, one‑off APIs).
• Anything that needs heavy app context to function.

Figure: Strategy fit matrix. The spectrum section is easier to use when each strategy is compared across the operating conditions the article actually names.

{
  "type": "matrix",
  "title": "Reuse strategy fit by operating condition",
  "xLabel": "Operating condition",
  "yLabel": "Reuse strategy",
  "valueLabel": "fit",
  "caption": "Local code optimizes discovery, packages optimize stable APIs and many consumers, submodules optimize pinned snapshots, and monorepos optimize lockstep change.",
  "data": [
    { "row": "Local", "column": "Low setup", "value": 5 },
    { "row": "Local", "column": "Stable API", "value": 1 },
    { "row": "Local", "column": "Independent release", "value": 1 },
    { "row": "Local", "column": "Audit pinning", "value": 1 },
    { "row": "Local", "column": "Atomic refactor", "value": 2 },
    { "row": "Local", "column": "Many consumers", "value": 1 },
    { "row": "Submodule", "column": "Low setup", "value": 2 },
    { "row": "Submodule", "column": "Stable API", "value": 2 },
    { "row": "Submodule", "column": "Independent release", "value": 3 },
    { "row": "Submodule", "column": "Audit pinning", "value": 5 },
    { "row": "Submodule", "column": "Atomic refactor", "value": 1 },
    { "row": "Submodule", "column": "Many consumers", "value": 2 },
    { "row": "Subtree", "column": "Low setup", "value": 3 },
    { "row": "Subtree", "column": "Stable API", "value": 2 },
    { "row": "Subtree", "column": "Independent release", "value": 3 },
    { "row": "Subtree", "column": "Audit pinning", "value": 4 },
    { "row": "Subtree", "column": "Atomic refactor", "value": 2 },
    { "row": "Subtree", "column": "Many consumers", "value": 2 },
    { "row": "Package", "column": "Low setup", "value": 3 },
    { "row": "Package", "column": "Stable API", "value": 5 },
    { "row": "Package", "column": "Independent release", "value": 5 },
    { "row": "Package", "column": "Audit pinning", "value": 4 },
    { "row": "Package", "column": "Atomic refactor", "value": 3 },
    { "row": "Package", "column": "Many consumers", "value": 5 },
    { "row": "Monorepo", "column": "Low setup", "value": 2 },
    { "row": "Monorepo", "column": "Stable API", "value": 4 },
    { "row": "Monorepo", "column": "Independent release", "value": 2 },
    { "row": "Monorepo", "column": "Audit pinning", "value": 3 },
    { "row": "Monorepo", "column": "Atomic refactor", "value": 5 },
    { "row": "Monorepo", "column": "Many consumers", "value": 4 }
  ]
}

Submodules vs packages: choose by operational model

• Choose submodules when you need pinned, auditable snapshots of an external project and do not plan to publish a stable API surface. Think “embed this repo at commit X and rarely change it.”
• Choose packages when you need stable consumption by many projects, quick installation, and semantic versioning. Think “I’m publishing a reusable capability with a contract.”
• Choose monorepo + internal packages when you need rapid co‑evolution across many libraries and apps with shared tooling—and still want the option to publish versioned artifacts outward.

There is no universal right answer; there is a right operational fit for your stage and audience.

Figure: Reuse evolution network. Reuse tends to move through stages rather than jumping directly from copy-paste to a mature package.

{
  "type": "network",
  "title": "Reuse evolution network",
  "caption": "The network shows the migration paths described in the article: local code, anti-corruption layers, packages, monorepo workspaces, and snapshot strategies.",
  "nodes": [
    { "id": "local", "label": "Local code", "group": "early", "value": 4 },
    { "id": "duplication", "label": "Duplication signal", "group": "signal", "value": 4 },
    { "id": "surface", "label": "Named API surface", "group": "control", "value": 5 },
    { "id": "tests", "label": "Contract tests", "group": "control", "value": 5 },
    { "id": "package", "label": "Versioned package", "group": "managed", "value": 5 },
    { "id": "workspace", "label": "Monorepo workspace", "group": "managed", "value": 4 },
    { "id": "snapshot", "label": "Submodule / subtree", "group": "snapshot", "value": 3 },
    { "id": "owner", "label": "Maintainer contract", "group": "governance", "value": 4 },
    { "id": "release", "label": "Release notes", "group": "governance", "value": 3 },
    { "id": "deprecate", "label": "Deprecation path", "group": "governance", "value": 3 }
  ],
  "links": [
    { "source": "local", "target": "duplication", "label": "same fix repeats" },
    { "source": "duplication", "target": "surface", "label": "extract smallest boundary" },
    { "source": "surface", "target": "tests", "label": "make contract inspectable" },
    { "source": "tests", "target": "package", "label": "stable independent consumption" },
    { "source": "tests", "target": "workspace", "label": "lockstep change" },
    { "source": "surface", "target": "snapshot", "label": "repo-level boundary" },
    { "source": "package", "target": "owner" },
    { "source": "workspace", "target": "owner" },
    { "source": "snapshot", "target": "owner" },
    { "source": "owner", "target": "release" },
    { "source": "release", "target": "deprecate" }
  ]
}

Evolution patterns (how reuse grows without breaking)

Start local, extract later

Build in the app until the shape stabilizes; then extract the smallest coherent abstraction. Don’t prematurely publish raw experiments as “core.”

Strangler fig for shared code

When you notice duplication, publish a new package and migrate each repo piece‑by‑piece. During migration, leave adapters in old repos to avoid big‑bang rewrites.

Anti‑corruption layer

When consuming a messy third‑party API, wrap it in your own clean adapter inside a package. Your code depends on your interface, not theirs.

Deprecation with empathy

Announce a deprecation in the changelog. Provide a codemod or snippet to migrate. Give timelines. Old consumers shouldn’t wake up to broken builds.

Common anti‑patterns and how to avoid them

The God Package
A giant “utils” library that knows everything about everything. It grows until nothing is safe to change.
→ Split by domain (auth, formatting, storage) with crisp contracts.

Hidden cross‑repo coupling
Two packages quietly import each other or reach into each other’s internals.
→ Enforce dependency rules (no cycles); publish only the public surface.

Leaky environment assumptions
Library reads process.env, fetches global window, or assumes a specific framework version.
→ Accept dependencies via constructor/config; push framework coupling to adapters.

Lockstep version pinning everywhere
Everything bumps major versions together, forcing synchronized releases.
→ Only bump what breaks; use change detection to release the minimal set.

Premature publication
Publishing experiments too early calcifies bad shapes.
→ Prove value in one codebase, extract after patterns emerge.

Thinking like a platform: a mental model

Your codebase is an ecosystem. At the center are paved paths: the standards you want every app to use (logging, auth, monitoring, UI tokens). Those paved paths live as packages with clear contracts and docs. Around them are apps and services that compose these packages.

• Packages are products with users. They need versioning, docs, and support.
• Apps are consumers; they depend on a stable experience and minimal surprise.
• The repo structure (monorepo, multi‑repo with packages, submodules) is the marketplace that moves code between producers and consumers.

This mindset shifts decisions from “What can we technically do?” to “What experience do we want our consumers (including future us) to have?”

Documentation that scales with reuse

• README as an entry point – one‑screen overview, install, quick start, example usage.
• CHANGELOG as narrative – what changed, why, and how to migrate.
• Examples folder – small, real scenarios that compile.
• Types as docs – in TS, exported types and JSDoc are a living spec.
• Design notes – a short ADR (architecture decision record) stating the package’s purpose and trade‑offs.

Good docs reduce support load and make your package the obvious choice instead of a mysterious internal secret.

Security & governance (the unglamorous multipliers)

• Least privilege – private repos/registries for private packages; separate tokens.
• Provenance – signed commits/releases; verify published artifacts came from CI.
• Licensing – declare how others can use it, even if “internal only.”
• API review – treat breaking changes like an RFC; require approval.
• Telemetry (opt‑in) – error reporting can tell you what breaks in the field.

These aren’t bureaucracy; they are force multipliers once you have many consumers.

A simple decision aid (keep it pragmatic)

• Is this used in ≥3 places and stable? → Extract.
• Do we need semantic versioning and easy install? → Package.
• Do we need pinning and rare updates? → Submodule (or subtree).
• Do we need atomically refactoring 5 libs and 3 apps today? → Monorepo internal packages.
• Still exploring? → Keep local; design the interface while you learn.

Write it down. A one‑page reuse policy removes debate from every PR.

What this buys you (beyond fewer copies)

• Educational leverage – your best patterns are captured and taught by the code itself. New contributors learn by importing good abstractions.
• Exploratory freedom – you can try ideas locally without committing the world; when they mature, they graduate to shared packages.
• Operational calm – a bug is fixed once, in one place, with tests, and flows outward with a version number.
• Strategic compound interest – every small package that stays healthy adds velocity to every future project.

That’s the real promise: not tooling wizardry, but a system where good ideas move easily and stay good as they spread.

If you only remember five things

1. Let change flow through a single channel (package, not copies).
2. Narrow the public surface; hide everything else.
3. Treat tests and docs as contracts.
4. Version intentionally; communicate breaking changes.
5. Choose submodule / package / monorepo by your operational needs, not fashion.

Build like you’ll be the one maintaining it—because you will be. Reuse is not about avoiding work today; it’s about creating a world where the same work makes every project better, every time.

Research Question

When should shared engineering code become a package, a submodule, a subtree, or remain local, and what evidence should guide that decision before reuse becomes a governance problem?

The practical tension is that copying code feels cheap at the beginning. It preserves momentum, avoids package setup, and keeps the local feature moving. The cost appears later, after behavior diverges, tests stop representing a shared contract, and security fixes have to be remembered across many repositories. The research question is therefore not simply "which reuse tool is best." It is how to decide which reuse boundary matches the change pattern, ownership model, release cadence, and risk of the code being shared.

Method

I treated reuse strategy as a dependency-governance study. The method was to turn the article's qualitative principles into an explicit decision matrix and then map each reuse mechanism against the operational conditions where it tends to succeed or fail.

The first step is to identify the shared surface. If consumers only need a tiny stable function, the candidate might become a package. If consumers need a full repository snapshot, a submodule or subtree may be more honest. If the code changes in lockstep with several products, a monorepo or internal package workspace may reduce friction. If the code is still volatile and has one consumer, extraction is probably premature.

The second step is to score the operational model. Ownership, release cadence, test maturity, security sensitivity, and consumer count matter more than taste. A package without version discipline becomes a hidden copy-paste system. A submodule without operational comfort becomes a stuck pointer. A monorepo without boundaries becomes a large folder with unclear contracts.

Decision Model

flowchart TD
  A[Candidate shared code] --> B{More than one active consumer?}
  B -->|No| C[Keep local and document extraction trigger]
  B -->|Yes| D{Changes in lockstep?}
  D -->|Yes| E[Workspace or monorepo package]
  D -->|No| F{Stable narrow API?}
  F -->|Yes| G[Versioned package]
  F -->|No| H{Need repository snapshot?}
  H -->|Yes| I[Submodule or subtree with owner contract]
  H -->|No| J[Anti-corruption layer before extraction]
  G --> K[Contract tests and semver]
  E --> K
  I --> L[Pointer update and security patch process]
  J --> M[Reassess after surface stabilizes]

The model makes the hidden variable visible: operational capacity. A team should not choose packages because packages feel professional; it should choose packages when it can support versioning, release notes, contract tests, and consumer upgrade paths. Likewise, a team should not choose submodules because they avoid publishing; it should choose them when repository-level linkage is the honest boundary and the team is willing to manage pointer updates.

Figure: Extraction readiness surface. Repository evidence should decide whether a module is ready for extraction: consumer pressure alone is not enough if the API is still volatile.

{
  "type": "scatter",
  "title": "Extraction readiness surface",
  "xLabel": "API stability",
  "yLabel": "Consumer pressure",
  "caption": "High consumer pressure with low stability wants an anti-corruption layer or workspace. Stable shared capabilities are package candidates.",
  "data": [
    { "label": "One-off app glue", "x": 1, "y": 1 },
    { "label": "Volatile feature", "x": 2, "y": 2 },
    { "label": "Shared utility", "x": 4, "y": 4 },
    { "label": "Schema package", "x": 5, "y": 4 },
    { "label": "Data client", "x": 4, "y": 5 },
    { "label": "Workspace module", "x": 3, "y": 5 }
  ]
}

Evidence Matrix

The article's current evidence is principle-driven. That is useful, but a research-grade version needs explicit operating signals. These signals can be gathered from repositories before a migration or extraction decision.

Control Points

The first control point is API shape. Shared code needs a named, narrow surface before it deserves distribution. If consumers rely on internals, the next move is not publishing. The next move is an anti-corruption layer that makes the intended boundary real.

The second control point is tests. Tests become the contract between the shared module and its consumers. Without tests, packaging can create a false sense of safety because the code has a version number but no reliable signal that behavior stayed stable.

The third control point is release policy. Semantic versioning is only useful when maintainers actually distinguish patches, features, and breaking changes. If a module will be updated casually with no release notes, it may still be useful internally, but downstream teams should not treat it as a stable dependency.

The fourth control point is ownership. Every shared module needs a maintainer of last resort. That owner is responsible for reviewing changes, responding to security fixes, and deciding when to deprecate or split the module. Without ownership, shared code becomes public infrastructure with private accountability.

Figure: Coordination burden as consumers grow. The failure-mode section becomes more concrete when copy-paste drift is compared with package and monorepo governance as consumer count rises.

{
  "type": "line",
  "title": "Coordination burden as consumers grow",
  "xLabel": "Active consumers",
  "yLabel": "Governance burden",
  "caption": "Copy-paste starts cheap but becomes expensive once fixes must propagate. Packages and monorepos begin with process overhead but scale with clearer ownership.",
  "data": [
    { "series": "Copy-paste", "x": 1, "y": 1 },
    { "series": "Copy-paste", "x": 2, "y": 3 },
    { "series": "Copy-paste", "x": 3, "y": 5 },
    { "series": "Copy-paste", "x": 4, "y": 7 },
    { "series": "Copy-paste", "x": 5, "y": 9 },
    { "series": "Package", "x": 1, "y": 3 },
    { "series": "Package", "x": 2, "y": 3 },
    { "series": "Package", "x": 3, "y": 4 },
    { "series": "Package", "x": 4, "y": 4 },
    { "series": "Package", "x": 5, "y": 5 },
    { "series": "Monorepo", "x": 1, "y": 4 },
    { "series": "Monorepo", "x": 2, "y": 4 },
    { "series": "Monorepo", "x": 3, "y": 4 },
    { "series": "Monorepo", "x": 4, "y": 5 },
    { "series": "Monorepo", "x": 5, "y": 5 }
  ]
}

Failure Modes

Implications For Engineering And Scientific Workflows

Reusable code becomes more important as the platform starts supporting deeper scientific and data-center-backed work. Experiments, simulations, ingestion jobs, model-evaluation harnesses, and analysis dashboards will share utilities. If those utilities spread through copying, the research surface becomes harder to trust because two studies that appear to use the same tool may actually be running diverged code.

The implication is that reuse strategy is part of research infrastructure. A benchmark helper, data parser, schema validator, or access-control module is not just "developer convenience." It shapes whether results are reproducible and whether safety fixes reach every workflow. The right reuse mechanism should therefore preserve provenance: which version of the helper was used, who owns it, how it was tested, and how downstream projects receive updates.

For Codex-managed content, this lab becomes a useful pillar because it can anchor future notes about package extraction, monorepo boundaries, internal SDKs, and experimental reproducibility. The next layer of evidence should come from repository scans: duplicated files, import graphs, package boundaries, test coverage, release cadence, and security-sensitive modules.

Next Study Questions

• What import-graph signals best predict that local shared code is ready to become a package?
• How should Codex detect duplicated logic across repositories without mistaking similar scaffolding for true reuse debt?
• Which modules in the current platform are security-sensitive enough to require centralized ownership?
• What release-note shape is sufficient for internal packages used by research and engineering workflows?
• Can repository provenance be attached to Labs articles so readers know exactly which helper version supported an experiment?