Include Available Version markers when documenting new features

[Cheddam]

Pages affected

• Manipulating Eager Loading Queries
• Validation constraints via Symfony Validator

Description

Often documentation for new features lands in this repo (and is published) before the version it becomes available in is shipped. Even after it ships, some projects may not be updated immediately. This can create some confusion when a developer discovers and attempts to reference documentation for a feature that isn't yet available in their project.

To combat this, I propose introducing a guideline to encourage the inclusion of an 'Available from x.y' flag above any newly created documentation. In addition, I'd suggest we prune these flags when branching a new major version of the docs, since all flagged documentation can be assumed to be current at that point.

Validations

• Check that there isn't already an issue that reports the same problem

[maxime-rainville]

This could be nice, but I'm also a bit concerned that it could add quite a bit of overhead when drafting doc.

If we did have a "this got release in 5.2" badge, we probably would need a process for removing those badges. Maybe when we tag a new major or when the minor where this shipped goes EOL.

Once upon a time, you could consult the doc specific minor release. This sot of did the same thing.

[GuySartorelli]

If we did have a "this got release in 5.2" badge, we probably would need a process for removing those badges. Maybe when we tag a new major or when the minor where this shipped goes EOL.

I'd say just when we do a major. If the text for those 'badges' is the same across the board, we can just do a quick text search and remove them all at major time. So the CMS 6 docs won't talk about "only in cms 5.3" - but the CMS 5 docs still will, which is useful for people who are slow to upgrade.

I don't think it adds much overhead.

[GuySartorelli]

That said, it would also be very easy to update the docs site to have an option in the version dropdown for each minor release, if you want to do that instead.