Deprecate drafts feature

[bluwy]

Changes

Deprecate drafts feature in favour of content collections

• Closes Drafts filtering behavior, configuration, flags, and docs needs cleanup. #7324, closes Draft frontmatter flag not respected in collection #6400

Testing

Tested manually that the warning is logged in dev and build.

Docs

Added a changeset. The migration path is a bit bigger since it involves migrating to content collections first, then filtering draft. I linked to the related parts in docs instead.

I'm also not sure if we need more documentation in the added @deprecated jsdoc. If we have more info in the published migration guide later, those fields could point to it instead?

/cc @withastro/maintainers-docs for feedback!

[changeset-bot]

🦋 Changeset detected

Latest commit: 4435deb

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[sarah11918]

Hey @bluwy! Quick touch up to the changeset, and I've left a question for @delucis since I can't remember the last time we deprecated something on this page and I want to make sure we're doing it correctly. 😄

[sarah11918]

@delucis - Is there any special formatting we need to adhere to for the deprecated entry here?

[delucis]

We don’t actually display @deprecated comments in docs yet, so now’s our chance to decide a format if we want!

I can imagine generating something like this? Where the contents of the comments follow the leading Deprecated:.

Or even something like this depending on how highlighted we want it:

So given that, I guess it depends if you think specific wording would be clearest there @sarah11918?

[bluwy]

Actually, checking where I adopted the since version X pattern which is from errors-data.ts, it looks like we already render it today:

So perhaps another place to align if we want to make @deprecated work nicely everywhere.

[delucis]

Ah OK, yes, we could implement a similar pattern in the config reference if we like how the error generation script does this.

In this example I don’t love how basically a full sentence is split across heading and paragraph, so if we like the chunkier aside rendering, I would probably argue we should end up with something that looks more like:

⚠️ Deprecated
Deprecated since version 2.6. Use content collections instead.

In which case, best for that to be reflected in the JSDoc comment too:

Suggested change

	* @deprecated since version 3.0. Use content collections instead.
	* @deprecated Deprecated since version 2.6. Use content collections instead.

[bluwy]

I pushed a commit to update the @deprecated tag to be a proper sentence instead 👍

[bluwy]

Thanks for the review! I've also updated the RSS readme (missed that). Marked the drafts option deprecated too, but I'm not sure if that's consistent with how we usually mark things deprecated.

[sarah11918]

Just noting that for v3.0, we will actually be using this here: #8158

[delucis]

Thanks for updating the @deprecated tags @bluwy! LGTM!