Add MIGRATION.md migration guide
#452
Conversation
We now have newer, better actions to achieve the same results: - `ios_generate_strings_file_from_code` - `ios_extract_keys_from_strings_files` - `ios_download_strings_files_from_glotpress` - `ios_merge_strings_files`
Co-authored-by: Olivier Halligon <[email protected]>
…legacy-localization-tooling Remove legacy localisation script references and actions
…o that the same name can be reused across actions
…to avoid relying on implementation details
…d of manually parsing it
…am-on-ios_get_app_version Add configuration item for .xcconfig file in `ios_get_app_version`
Co-authored-by: Olivier Halligon <[email protected]>
…deliver-file Remove Deliverfile related functionality
…or-ios_get_app_version Additional tests for `ios_get_app_version`
Co-authored-by: Olivier Halligon <[email protected]>
…app_version` and the `Deliverfile`
| - [ ] Make sure you added an entry in [the `CHANGELOG.md` file](https://github.com/wordpress-mobile/release-toolkit/blob/trunk/CHANGELOG.md#trunk) to describe your changes under the appropriate existing `###` subsection of the existing `## Trunk` section. |
There was a problem hiding this comment.
@AliSoftware: I noticed a small typo in the .github/PULL_REQUEST_TEMPLATE.md ("approprioate"), and while editing it I realised it would be nice to mention the MIGRATION.md here as well. Please let me know if you think this makes sense, otherwise I can just revert it.
There was a problem hiding this comment.
Monday morning, new week, fresh mind, and now I'm wondering if having a separate document is worth it vs including those instructions directly in the CHANGELOG.md as a dedicated paragraph 🤔 @wordpress-mobile/apps-infrastructure what do you think?
On one hand, I was the one to initially suggest a Migration Guide, and I like having a dedicated document for how to adopt breaking changes in client repos, On the other hand, having a separate document would me a separate document to maintain and update, having to update our release scripts to ensure it has been updated when we are about to release a major version, and having people to know about the document when they adopt a new version so that they remember to check the separate file to know the instructions. So I kinda think I might have changed my mind and would maybe prefer to put this all in the CHANGELOG.md after.
But this also depends on how much we want to write in such Migration Guide. If those migrations end up having a lot of things to write about and containing long paragraphs, then it's likely worth a separate document. If it's smaller content, maybe not?
Also, other OSS repos like Alamofire have a separate document for each major version bump — as opposed to have a single document with sections for each version. Could be worth considering such an option. But that being said, they have way more things to write about in each of those migration guides, because each of their major version bumps was significant, while in our cases we are more likely (at least at this stage of the toolkit's life) to do major version bumps and small breaking changes more often rather than hold them for a while a do a big refactoring and major bump with a lot of breaking changes packed in a single release, so… 🤔
I had the exact same thought when I first heard it: this could just be part of the It's not one of the primary aims of the document and maybe it is a bit of wishful thinking from my side, but I also think of it as a communication tool between the Toolkit and the various clients, potentially providing more details on the reasoning behind changes, what's their goal and long term view, so the users can also be better prepared on their side (for example in the case of not depending anymore on Deliverfile or on env. vars).
To avoid extra effort from the beginning, we could also consider starting with a section in the change log, see how it goes, and then move to a separate document if we think it makes sense, as this would be less disruptive than the other way around 🤔
Exactly my thinking. I'm still somewhat on the fence on this one. My first instinct is that there will always be more context and useful information to add and that this could clutter the change log, which should be a short bullet list of the main changes for each version.
Ah, this can be an interesting approach. As you also said, to me it makes more sense for them as they have way more things to write about and a more complex migration procedure. |
👍 Go for it |
|
Replaced by #490 |
What does it do?
This PR proposes the usage of a migration guide in the form of the file
MIGRATION.md.The idea is that a guide like this can be specially useful to provide more context for a successful migration between major releases of the
release-toolkit, giving more information about deprecations, clean-ups that the clients can do, how to deal with breaking changes and any other adaptations that the hosting projects need to implement when migrating to a new version.A process to update the
MIGRATION.mdfile can be very similar to the one followed byCHANGELOG.md:## Migrating to Trunksection## Migrating to Trunkcan be changed to## Migrating to 7.0.0, for example## Migrating to Trunksection is added to contain the updates for the next versionI've initially organised the migration topics into two main subsections,
Considerations for breaking changesandClean-ups, which I believe will be common cases; more subsections can be added or a different grouping can be done as we see fit.This is the discussion I had with @AliSoftware that originated this PR.
Related PRs
MIGRATION.mdmigration guide iangmaia/release-toolkit#4Checklist before requesting a review
bundle exec rubocopto test for code style violations and recommendationsspecs/*_spec.rb) if applicablebundle exec rspecto run the whole test suite and ensure all your tests passCHANGELOG.mdfile to describe your changes under the appropriate existing###subsection of the existing## Trunksection.