Deprecation schedule and versioning

For most projects, when we announce the deprecation of any functions, there will usually be a transition period during which the code will still work with the latest release, but whenever those functions are called, they will be met with a deprecation warning. I think we need to define a clear schedule for this, including when and how many major releases will be used to remove the deprecated features.

There are two things that might need to be treated separately: deprecation of content rendered for the user to see in the file itself, and deprecation of features developers use. We would want to be much more careful about deprecating things the user sees, while deprecating features for developers might be on a slightly shorter timeline. As the spec and associated software ecosystem mature, these will be very important for making it right on a reasonable timeline for breaking changes.

I foresee that we might need to create a document for this, or, better yet, make this schedule part of the spec, so all users can see the change logs and specifically see when changes will take effect and be enforced. Not all projects can be changed or updated at the same time, so having a clear timeline will be beneficial.

The issue names no files, tests, or entry points. Start by locating the repository’s specification and existing versioning or changelog documentation, then determine where a deprecation schedule would belong and how user-visible content differs from developer-facing features. Done would require an agreed schedule and a documented place for future deprecation timelines.

Written by the indexing model from the issue text.