We will follow a single, invented dependency through a full cycle. Your Node.js service uses a date-formatting package called fastdate. Nothing here is specific to Node; Python, Java, .NET and PHP ecosystems have the same ideas with different file names.

Step 1: reading the version number

Semantic Versioning, written down at semver.org, says a version has three numbers: MAJOR.MINOR.PATCH. A patch release (2.3.0 to 2.3.1) contains backward-compatible bug fixes. A minor release (2.3.1 to 2.4.0) adds features in a backward-compatible way. A major release (2.4.0 to 3.0.0) may break things. Lines starting at 0.x are treated as unstable: anything may change at any time.

Note the wording. It is a promise made by the library author, written in a convention. Nothing checks it.

Step 2: what your manifest actually says

In package.json you wrote ^2.3.0. The caret means “compatible with 2.3.0”, which npm treats as at least 2.3.0 and below 3.0.0. So 2.3.5, 2.4.0 and 2.9.1 are all acceptable; 3.0.0 is not. A tilde, ~2.3.0, is stricter: patches only, so below 2.4.0. An exact version with no symbol pins one release. For versions starting 0., the caret is tighter: ^0.3.1 allows only 0.3.x, because minor bumps in 0.x are allowed to break. Other ecosystems spell this differently (Python has ~= for a compatible release, Maven uses bracket ranges), so check the syntax for your tool.

Here is the problem with ranges alone. On Monday you install and get 2.3.0. On Thursday your colleague installs and gets 2.4.0, because it has been released in between. Same manifest, different code. And so does your build server, at whichever minute it runs. That is how “works on my machine” gets recreated through version drift.

Step 3: the lockfile freezes a decision

The lockfile (package-lock.json, yarn.lock, poetry.lock, Pipfile.lock, composer.lock, and so on) records the exact version that was resolved for every dependency, including dependencies of dependencies, often with a checksum. Your direct list might have twelve packages; the lockfile may list several hundred.

Install from the lockfile and everyone gets the same tree: you, your teammate, CI, production. In npm, the npm ci command exists for exactly this: it installs strictly from the lockfile and fails if the lockfile and manifest disagree, which is what you want in a pipeline. Commit the lockfile to the repository for applications. For libraries you publish, the lockfile is not shipped to consumers, so you should also test against the newest versions your range allows.

Step 4: upgrading on purpose

Now fastdate 2.5.0 is out and you want it. You run the update command; the lockfile changes from 2.3.0 to 2.5.0 and the diff is reviewed in a pull request like any other code. Run the tests. If they pass, merge. If something breaks, you revert one file and you are back exactly where you were. The upgrade became an explicit, reviewable, reversible event instead of something that happens to you.

A major version is a different exercise. Moving to 3.0.0 means editing the range in the manifest, reading the release notes or migration guide, and expecting code changes: renamed functions, changed defaults, dropped support for an older runtime. Budget real time, and do it in its own pull request so that a failure points at one cause.

Step 5: when the promise is broken

Suppose 2.4.0 quietly changes how a null date is formatted, and your invoice screen now prints “Invalid Date”. By the convention that should have been a major release. It happens, because authors cannot foresee every use, and because “breaking” depends on who is looking: a fix to a bug that your code relied on is a break for you. Tests that cover your real usage of the library are the only defence that works. The lockfile limits when the surprise reaches you, but it does not prevent it.

The part people forget: transitive dependencies and security

Your lockfile also freezes vulnerable versions. A package pinned for two years does not receive the security fix that was released last month. So the aim is not “never change”, it is “change deliberately and often”. Tools such as Dependabot and Renovate open automated pull requests for new versions, and audit commands (npm audit for example) report known vulnerabilities in the locked tree. Small, regular upgrades are far easier than a three-year jump where fifteen major versions have piled up.

Be wary of the opposite habit as well: using “latest” or very loose ranges in a production build. That makes a deployment depend on whatever was published an hour ago, and it has caused real outages and supply-chain incidents across the industry when a package was compromised or broken upstream.

A workable routine

  • Keep the manifest ranges reasonably tight and commit the lockfile.
  • Install from the lockfile in CI and in the container build.
  • Let a bot propose upgrades weekly; merge patches quickly, schedule minors, plan majors.
  • Rely on tests of your own behaviour, not on the version number, to decide whether an upgrade is safe.

Figures and names in the examples are illustrative, including the package fastdate.

Leave a Reply

Trending