NEWS & UPGRADING.md #436
Labels
Comments
algernon
added a commit
that referenced
this issue
Oct 22, 2018
For easier navigation of changes, this introduces `NEWS.md`, a high-level overview of important or otherwise noteworthy changes. It is a short list only, with just the bare minimum of details. The new `UPGRADING.md` on the other hand, is a much more detailed document, and contains the upgrade notes from plugins too. The plugin docs now document the current version of the plugins only. The intent is to have both a short overview (`NEWS.md`), and a detailed guide (`UPGRADING.md`). The former will contain historical entries too, while the later is meant to be an upgrade guide from the previous version to the most recent one, with old notes eventually removed. Fixes #436. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
With having most official plugins in a monorepo, it would make sense to collect all the upgrade notes into a single place (
UPGRADING.md). It would also be great if we had some kind of high-level changelog, that's friendlier to browse through than git logs. This new document could also include plugin news, so thedoc/plugin/*.mdstuff would be documentation for the most recent version, and that alone.This setup would make the plugin docs more useful, and upgrading for users easier, as they'd only have one place to look for notes.
In my mind, the difference between
NEWS.mdandUPGRADING.mdwould be that the former would list changes, possibly for multiple versions as time goes by, whileUPGRADING.mdwould be upgrade notes only, changes that introduced incompatible APIs, or deprecated others... where the end-user is likely to need a bit of work on their sketch.NEWSwould also list new features, which would not be inUPGRADING. Similarly,UPGRADINGwould be more detailed.The text was updated successfully, but these errors were encountered: