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

[Chore] Upgrade guide tracker for released and unreleased features #1766

Merged
merged 5 commits into from
Apr 2, 2024

Conversation

art-alexeyenko
Copy link
Contributor

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

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Chore

@art-alexeyenko art-alexeyenko requested a review from a team March 27, 2024 18:34
@art-alexeyenko art-alexeyenko changed the title [Chore] Upgrade guide tracker for work in progress [Chore] Upgrade guide tracker for released and unreleased features Mar 28, 2024
docs/UPGRADING.md Outdated Show resolved Hide resolved
docs/UPGRADING.md Outdated Show resolved Hide resolved
Copy link
Contributor

@illiakovalenko illiakovalenko left a 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

@illiakovalenko
Copy link
Contributor

@kendoce, @art-alexeyenko
Another idea, may be it might be better even, need to explore
There is a way to create a guide under wiki tab that is more appropriate than an .md file
See example

@art-alexeyenko
Copy link
Contributor Author

@illiakovalenko the decision to make a single .md file for this is deliberate, for a few reasons:

  1. Maintainability. We can realistically only provide update instructions incrementally (21.7->21.8, 21.8->22.0 etc). If we are doing .md files we can quickly get a bloated folder that is annoying to find correct files in
  2. Findability. It would also be annoying for customers to switch between files in a large folder, it's much easier to do a ctrl+F to find a relevant version in a single file

Wiki is worth exploring though, thank you for the idea

@art-alexeyenko
Copy link
Contributor Author

@illiakovalenko please check this updated structure.
It should make the docs more orderly, while not complicating the navigation too much.

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?
CC @kendoce

Copy link
Contributor

@illiakovalenko illiakovalenko left a 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

docs/upgrades/21.x/21.7.md Outdated Show resolved Hide resolved
UPGRADING.md Outdated Show resolved Hide resolved
UPGRADING.md Outdated Show resolved Hide resolved
Copy link
Contributor

@illiakovalenko illiakovalenko left a 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 👍

@art-alexeyenko art-alexeyenko merged commit 461b4ee into dev Apr 2, 2024
1 check passed
@art-alexeyenko art-alexeyenko deleted the chore/jss-1627-upgrade-guide-monorepo branch April 2, 2024 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants