Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Narrowing scope of docs for breaking changes, currently in reference/changelog and how-to/migrations #632

Closed
consideRatio opened this issue Jul 1, 2023 · 1 comment · Fixed by #637

Comments

@consideRatio
Copy link
Member

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.

@minrk
Copy link
Member

minrk commented Jul 3, 2023

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants