Proposal: a status vocabulary for READMEs that aren't software

[ChristopherA]

Our secure template gives every new Blockchain Commons README a Status section, and our Development Phases document is where its statuses come from: Research, then Alpha through Final on the release path, then Superseded, Unsupported or Withdrawn when a repo leaves it. I've been working through our READMEs to bring them up to a common standard, and the Status section is where I keep running into the edges of that document.

I read the READMEs of 93 of our repos: every repo pushed in the past year, plus a handful of older flagships. 67 of them have a Status heading. 48 of those use a phase from Development Phases. The other 19 say something the document has no word for, and they fall into three groups:

• Books, courses and guides. SmartCustodyBook says "First Release 2019-09-16", XID-Quickstart says "Experimental", Pseudonymity-Guide says "Edited". A book doesn't go through Alpha and Beta.
• Hubs. Community, Gordian and crypto-commons say "Varied"; Gordian-Developer-Community says "Work in Progress"; SmartCustody says "Ongoing". A hub collects projects at different stages.
• Software with terms of its own. "Production-Ready", "Feature-Complete Beta", "Preview", "Development Preview", "Reference Implementation", and a few bare "Status" headings with no state at all.

Another 26 repos have no Status section.

We already have two other vocabularies for this. The Research repo rates each BCR on a specification ladder: Research, Reference Implementation, Multiple Implementations, Standards Track, Standardized. And in Community issue #66, Shannon proposed a content ladder for books and guides back in 2021: Drafting, Completed, Edited, Reviewed, with Edited around v0.9 and Reviewed at v1.0. Pseudonymity-Guide's "Edited" comes from that proposal. The issue is still open.

What I'm proposing is one heading, ## Status - <state>, with the allowed states set by the kind of repo:

Kind of repo	Status vocabulary
Libraries, command-line tools, apps, services, experiments	Development Phases
Specifications (Research, IETF drafts)	The Research specification ladder
Books, courses, guides, content websites	Shannon's content ladder: Drafting, Completed, Edited, Reviewed
Hubs	Varied, with each listed project showing its own status
Any kind	Superseded, Unsupported or Withdrawn

The last row matters for older repos. As we work out which ones to deprecate, archive or retire, every kind needs the same end states.

For the software repos using terms outside the list, here is a first guess at where each lands. The maintainers know their repos better than I do, so treat these as questions:

Used now	Proposed
Production-Ready	Final, or Feature-Complete if a security review hasn't happened
Feature-Complete Beta	Feature-Complete
Preview, Development Preview	Alpha
Work-in-Progress (0.8)	Alpha, since Development Phases says a version below 1.0 is at best alpha
Reference Implementation (on a library)	The library's own phase, with the specification's status kept on the specification

I considered two alternatives. One is to put everything on Development Phases, which keeps a single list but gives a book no honest way to say it has been edited. The other is to add the missing words to Development Phases as one longer list, which mixes how mature software is, how far along a text is and how widely a specification is adopted, and I expect that mix to drift the same way the current headings have.

A few questions I haven't settled:

1. Does a website count as content or as an app? seedtool.info is an app; www.blockchaincommons.com is content.
2. Should a library that implements a specification show both its own phase and the specification's status, or link to the specification for the second?
3. Is "Experimental" the same as Drafting, or does the content ladder need it as a separate state?

What's your read? I'm especially interested in hearing from @wolfmcnally, @leonardocustodio and @shannona, whose repos make up most of the ones I surveyed. Once this settles I'll update Development Phases to cover all three ladders and close out issue #66.

-- Christopher Allen