-
Notifications
You must be signed in to change notification settings - Fork 276
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
[Chore] Upgrade guide tracker for released and unreleased features #1766
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
According to work item, our decision/idea was to create an "Upgrade guide" document per version
docs/upgrading/<version number>.md
I would prefer to avoid having a huge blanket of upgrades in a single file
It should be really easy to read and quickly check all the changes (also find previous changes if they are needed for customer), think about yourself as a customer.
Take a look at this example, you can find other examples in a network
cc @kendoce
@kendoce, @art-alexeyenko |
@illiakovalenko the decision to make a single .md file for this is deliberate, for a few reasons:
Wiki is worth exploring though, thank you for the idea |
@illiakovalenko please check this updated structure. I explored the wiki option. It seems wikis are hosted as a separate repo and we'd need a separate PR or push to updates them. I think wikis would be a better option with infrequent updates, but our aim here is to keep track of update guides every other PR or so. Plus, it's easier for community contributors to list the changes with current approach, if they choose to. For easier maintenance, do you think the gitignore file in release branches should be updated to not track the docs folder? Reduce potential conflicts when cherrypicking changes and keep the guides in one location only? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks better!
I think regarding .gitignore we can exclude only unreleased.md file.
And we need to update our publish scripts to make unreleased.md file empty in dev branch, when we publish a new minor/major canary in dev branch
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reopened one comment, feel free to push another minor change and merge after that 👍
Description / Motivation
Track future required upgrade steps with this one simple trick (file).
Adds a file to track unreleased changes to templates and add-ons (
JSS next
section) and upgrade instructions for released versions. The goal is to have a detailed list of changes for an upgrade guide ready before each release.Also modifies PR checklist. Each PR should include an entry to UPGRADING.md when applicable.
Types of changes