Harper repo taxonomy (5-type classification)

[Ethan-Arrowood]

This is a proposal for a classification system for every public-facing Harper repo. Each one has a clear maintenance obligation, test contract, versioning, and lifecycle and sets out to solve the "is this a template or an example, and is anyone keeping it alive?" ambiguity.

The 5 types

A repo's type is set by two questions: what is it for? (its contract) and what upkeep does it owe? (its maintenance band).

• Core — platform/plugins/first-party apps that produce the versions everyone consumes
• Template — build from it (two tiers: generic, in create-harper; and advanced/standalone)
• Example — read from it, a worked pattern
• Guide — follow it, an example plus narrated Learn content
• Snapshot — a moment in time, the frozen companion to a blog/talk/video

Core / Template / Example / Guide are the Maintained world; Snapshot is frozen. That maintained-vs-frozen split is the most important line in the whole thing.

What's in the doc

• The 5-type table with each type's obligations
• The rules that decide a type (contract decides the kind; functional surface decides test depth; maintenance obligation decides the band)
• The Guide↔Snapshot invariant — a dated artifact never references a living repo, so marketing/dev-rel snapshot a repo before building content on it (kills the "tutorial broke because the repo moved" problem)
• create-harper's role, version stamping via package.json engines, and a decided naming convention

For the review

The aim is alignment. I've been decisive throughout the proposal, but feedback and discussion is encouraged. The two spots most open to feedback are the naming convention (I've proposed a consistent template-/example-/guide- prefix) and the Snapshot archive trigger. Everything else we'll roll with unless there's a strong objection.

_{sent with Claude Opus 4.8}

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[kriszyp]

This looks great. I think the one point I might want to discuss/consider is categorizing types using names. I generally prefer to keep names clean and simple and separating out type/categorization into a separate tag, and GH's topics work perfectly for this. So consider putting "template"/"example" in the repo topic instead of repo name. This gives us the flexibility to apply different taxonomy dimensions in the future as well and not be constrained by a single one. This also makes it easier to change the "type" of the repo (I'd guess that there are some that might be on border/spectrum and could change over time as they mature) without renaming. Also, a type prefix is a bit hostile to auto-completion if you are working with multiple example repos, for example.

minor releases are non-breaking

Not quite true. Real semantic versioning: minor releases are claimed or believed to be non-breaking. By people (and AI). That are wrong a lot of the time.

And in reality v5 actually didn't break very many apps from an API perspective (most of upgrade problems have been more operational with internal complexity of refactorings, public API changes have had minimal impact), and there have been apps that have broken with 4.5->4.6->4.7 (sometimes just due to fixing bugs that users were "relying" on).

Anyway, the point is that is hard to really make hard decisions based on semantic version alone.

Anyway, this looks great, and if we want prefix-naming, that's fine, but these are the two things you asked for feedback on :).

[Ethan-Arrowood]

I would also like to drop the type from the name. When I was doing research for this I think my agent either hallucinated or found some sources claiming the typed naming was preferred. I can make edits later depending what others think.

Also I will adjust the specific language around the versioning, but that's definitely a minor detail

[alekshaugom]

This makes sense to me.

One thing I might add is that for this to last the test of time, we also need to establish a sunset process as part of this work (and perhaps a revival process).

What is the pattern for moving a maintained Template, Example, or Guide to something that is unmaintained? Should we set it as a public archive, and should any notes be added to it in the process of doing this? Then in reverse, when we want to give new life to an unmaintained Template, what is that process?

For me, the sunset and revival process is not obvious and might be worth documenting.