Frontmatter option to prevent guides from being published

[LeaVerou]

As discussed with @rviscomi, we should have a frontmatter option to keep a guide out of dist without deleting it from the repo.

Example use cases

• Drafts. We already have stubs in the repo, and drafts are essentially intermediate states between a stub and a full guide. While they could be technically developed in a PR that just doesn't get merged until the guide is done, it's typically easier to iterate with smaller PRs.
• Unpublish If serious issues are found with an existing guide we may want to temporarily remove the guide from dist until we fix the issues. We should not need to remove the guide to do that.
• Retired A guide that is no longer needed, as it was not offering uplift. We may not want to remove the guide, e.g. the use case may later become relevant again, as a new feature gets added to the platform.
• Future: A guide that is currently premature, e.g. authored in anticipation of shipping one or more upcoming features, or depending on other guides that are currently drafts. This is distinct from Draft: draft describes the guide content, Future depends on the environment.
• Regression hold for evals that dropped below threshold, withheld until fixed. Could even be set automatically.

This could also replace the hardcoded excludeFromBundling list (though I believe it's currently empty).

• Regression hold — evals dropped below threshold, auto-withheld until fixed. This could even be automatically set.

This could also help us get rid of the current hardcoded excludeFromBundling list (although I believe the list is empty).

API / Naming

The main design question is binary publish toggle vs an enum that distinguishes the cases above?

For a binary toggle:

• draft: true is common, but only covers one kind of hiding.
• publish: false covers all of them, but booleans defaulting to true are discouraged — and avoiding that leads to double negatives like hidden: true.

An enum (e.g. status) adds some cognitive overhead, but enables smarter handling: a future guide can relax web-feature-id validation, a draft can skip it entirely, a regression-held guide can keep running in evals and flip back to published when uplift recovers, and diagnostics can flag guides stuck in draft too long. And frontmatter is all keywords anyway — true/false are keywords you type too.

Proposal: status: draft (with room for more values later). Covers the case that prompted this, and grows naturally into the rest. Or, we can even add values for (some of) the statuses above too and just handle them identically at first.

[rviscomi]

Curious to get thoughts from @paulirish and @micahjo7 if there's a preferred approach on the infra side

[paulirish]

works for me.

i'd go with with draft: text reason why its in draft state

[LeaVerou]

@paulirish I drafted #1024 last night before seeing your comment (mainly to see the extent of changes that would be required) so I just opened it as a draft PR.

I’ll update it to use draft: <any-truthy-string> (and recommend draft: true for the common case).
I do have some concerns about that shape (see below), but it also seems there is no obvious ideal design, so let's just ship the common case MVP first. (edit: done: #1027)

Concerns about draft: <freeform-reason>

My main worry is that it adds cognitive overhead to the common case, which is "This is a draft, because well, I’m still working on it". I’d be unsure what to put there for that. draft: true? draft: draft? Though that can be solved by establishing and documenting a convention.

In general, it seems to me that the cognitive overhead of having to provide the additional signal (a description) doesn't translate to additional value. We can't do anything more with a freeform value than preventing publication, so it would basically work like a boolean + a forced comment (we can already have frontmatter comments via #). Though I can see it being useful in guide indices.

Unless you didn't mean completely freeform, but a sort of looser enum of sorts? I.e. use draft: true for the common case, and let the set of any other values grow organically by simply not enforcing any value-checking. Then, special handling can come after, as clusters of use cases emerge freely. The upside being flexibility, the downside being no checking for typos etc. I could see that! I didn't suggest it as the project so far leans on the stricter side wrt metadata validation, but I'm all for schema flexibility, heh.

Wrt the name draft, beyond regular drafts, some of the use cases above work better than others with it. For example, draft: future or draft: needs-review read fine, whereas draft: retracted or draft: regression-held look a bit weird. But it's NBD.

---

One issue with the name I proposed in the OP (status) is that there is an existing concept of guide status, which is around the presence of certain types of content (needs-evals, needs-investigation, etc). Perhaps publish_status would be more accurate, though it would be nice if we could find a single word. Perhaps publish? Or unpublish/hidden? But that’s a double negative…

Ok, the more I think of it, the more clear it becomes there is no obvious great solution that works for every case, so let's just do draft and be done with it. Drafts are the 90% case, so don't let my OP scope creep get in the way of that. 😅