Why the baseline is the manifest, not a tag¶
Every tool in this space answers one question: what was this package's previous version? Almost all of them answer it with the last git tag. skillup answers it with the git history of the package's own manifest.
That single difference is the reason it exists.
What a version means here¶
In a plugin marketplace the version is not a label on a release. It is the release. Both harnesses cache per plugin, per version:
Neither resolves a git ref; consumers track a branch. The documentation is blunt: "users only receive updates when you change this field."
So there is no artefact to publish. The branch is the artefact, and the version field decides whether anyone gets it.
What a tag baseline costs¶
Given a tag baseline, a tag stops being a record and becomes state the computation depends on. Three consequences follow, and they compound.
A missed tag is not a cosmetic problem¶
Delay tagging by a single merge and the next calculation reads a stale baseline. Demonstrated: with tagging one merge behind, two different states of a branch were assigned the same version. Same string, different content, on different machines — and nothing anywhere reports it.
An untagged repository is not a valid input¶
Run a tag-baselined tool against a repository that has never been tagged and it
computes from zero. In one case it proposed 0.1.0 for eight segments whose
real versions ranged to 0.22.0 — a regression of up to twenty-one minor
versions, presented as a normal result.
Adoption needs a bootstrap nobody can check¶
Before the tool is useful, someone must create one tag per package at the right version. Get one wrong and the error is invisible until that package next moves.
What the manifest already knows¶
The information a tag carries is already in the repository. The commit where a segment's version last changed is a fact recoverable from git:
…then find the newest commit whose value for version differs from its
parent's. That commit is the previous release. It cannot drift, cannot be
forgotten, and needs no maintenance, because it is a consequence of the change
rather than a record kept alongside it.
What this buys¶
- Correct on a repository with no tags. No seeding, no bootstrap.
- A missed tag costs visibility only. Tags become decoration — which is what most people wanted from them anyway.
- Tags can be back-filled, because the commit each version was set at is recoverable. Tagging can start whenever, and still be accurate about the past.
- Nothing to keep in step. There is no second source of truth to drift.
What it costs¶
Reading history is more expensive than reading a ref. Answering the question means walking commits that touched a directory and comparing a value across parents, where a tag lookup is O(1). For a marketplace of tens of segments this is imperceptible; for thousands of packages it might not be.
It assumes the version lives in a file that git tracks. A tag baseline works for anything. This works for packages whose version is committed — which is exactly the shape a plugin marketplace has, and not a general claim.
The rule underneath¶
When a tool needs to know what happened last time, prefer a fact the repository already records over a marker someone has to remember to leave.
A marker is a second source of truth, and a second source of truth is something that can disagree with the first. The disagreement is always silent, and always discovered later than you would like.