Add changeset for content layer experimental release

[ascorbic]

Changes

Adds the changeset docs for the experimental content layer release

Testing

Docs

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5e4b703

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

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

[github-actions]

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

[sarah11918]

Hi @ascorbic ! Great to see this take shape!

This is a bit of a deviation from our usual process, which is fine, but just want to mention that usually we'd get the JSDoc that ends up in docs all figured out first, and then we pull from that for the changeset. The reason for this is that the changeset is often a subset of the docs we'll post (because it doesn't have to list every single thing), and to make sure everything is consistent between both changeset and docs, it helps to have the larger content written first. (Use the same examples, same phrases etc.)

Can we maybe consider this what you'd be proposing for the docs, and we can negotiate "full docs" in here first, then use that to add to the implementation PR and whittle down the changeset from that?

[ascorbic]

@sarah11918 I did it like this because there isn't a flag, so there's no JSDoc for it. Is there somewhere else it could go?

[sarah11918]

@ascorbic Then this is really a departure from how we usually release experimental features! 😅

There's no flag to enable? Is there a particular reason we're doing it this way? (Might help me figure out where we're going to put docs, because usually they'd be with the documentation to enable the flag.)

[ascorbic]

@sarah11918 the initial reason was because the content config file doesn't have access to the astro config, so we used a type instead. However off the back of this we've had a discussion and worked out a way to implement it with a flag so I'll do that instead.

[sarah11918]

@ascorbic Not gonna lie, that makes it simpler for docs since we already have an established procedure! (Not that I wouldn't have been able to come up with something, of course, but it would have meant some potentially conflicting info on the content collections page itself -- do this, but if you're using experimental, do this.)

And from our stats we know that only around 3% of people have ANY of experimental flags enabled, so if we can avoid adding complexity in the main docs when we don't have to, it just makes for cleaner docs.

As for this PR, maybe we can add the @docs content in the types file here too, then we can hash out all the docs (config for the flag, changeset) together in this one PR?

Typically they'll be pretty close to each other, but the docs should be minimally complete (for an experimental feature), then we refer people to the RFC link for discussion, input, and to keep up to the minute with it. The changeset can be taken from that, but can also be a bit more hype to introduce the feature, and you might choose to not be as doc-y there.

[ascorbic]

The changeset here is very much focussed on how to migrate and try it out. Would that same format be appropriate for the flag docs, or should it be approached more as a standalone thing ("here's how to use it" vs "here's how to try it with your current content")

[sarah11918]

I think both are appropriate! Ideally, it should be enough for someone to (understand how to) get started trying it out.

We're pretty flexible on whatever feels helpful to someone wanting to experiment with a feature. You can see the others here: https://docs.astro.build/en/reference/configuration-reference/#experimental-flags
(actions, server islands, and env were all similarly hyped features, so they'd be the best comparisons)

I think showing the migration makes perfect sense in this case, since a LOT of people will already be using collections. I do also see this feature opening up the feature to those who use e.g. remote content, and so for whom using existing content collections was a non-starter. But now, they want to try this version of collections. (I see this sentiment a lot, so we can't just assume everyone will already be using collections!)

Maybe a structure like:

• intro/description/hype
• how to enable it
• how to USE this new iteration of collections (pointing out WHICH of the existing content collections docs may be appropriate? e.g. "You get all the benefits of the existing content collections feature, with the same helpful schema/APIs with a few key differences. Additionally, you have the option to specify a source loader... "
• how to upgrade an existing collection (which focuses on the differences)
• See the RFC for discussion/more info standard line.

I think that could all be fair game here!

[sarah11918]

Love this! Just two thoughts that I think might be nice tiny additions that give a good bang for your buck! Do with them what you will, but otherwise, this looks perfect!

[sarah11918]

Suggested change

	You can then create collections in your `src/content/config.ts` using the Content Layer API.
	You can then create collections in your `src/content/config.ts` the Content Layer API in addition to continuing to use the existing content collections API. You can configure on a per-collection basis, and your schema may contain both kinds of collections at once.

Because this is abridged, we don't show the "migrate to / from" nor do we mention that you can keep your existing collections if you don't want to move them all over immediately. So I think frontloading this idea makes sense here for more confident adoption!

[ascorbic]

I've included a similar sentence in the first paragraph, so I'm not sure this is needed too.