You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We have a changelog and a v16 migration page. I find myself needing to better know what goes where, and I would like to see discussion from this issue conclude that.
Documentation goals
As little as reasonable is documented in multiple places
Its made clear what content is put in changelog, and what and when to put something outside the changelog into a major version migration page.
The major version changelog entry links to migration docs if there is any.
This is to ensure it remains feasible for z2jh and tljh to reference the changelog without needing to know if and where there is more detailed migration docs. They do so systematically for all dependencies, and its nice to not make an exception.
Suggestion
The migration page currently describes its content as "what to pay attention to when upgrading". I think we should narrow the migration docs to how to update old config to new config, and let the changelog be what to pay attention to overall and the migration to focus on how-to update config.
The text was updated successfully, but these errors were encountered:
I think for the most part, changelog should be restricted to answering "what changed?" in direct, factual lists, and separate docs like migration docs should have more detailed explanations answering "what should I do about it?" when there's something to be done (most releases don't have anything to do here, but 16 surely will).
We have a changelog and a v16 migration page. I find myself needing to better know what goes where, and I would like to see discussion from this issue conclude that.
Documentation goals
This is to ensure it remains feasible for z2jh and tljh to reference the changelog without needing to know if and where there is more detailed migration docs. They do so systematically for all dependencies, and its nice to not make an exception.
Suggestion
The migration page currently describes its content as
"what to pay attention to when upgrading"
. I think we should narrow the migration docs to how to update old config to new config, and let the changelog be what to pay attention to overall and the migration to focus on how-to update config.The text was updated successfully, but these errors were encountered: