flame-engine
Create migration guide for 2.0
Similar to #470, only this should be the transition guide from 1.0 to 2.0.
I think the main reason why #470 failed to materialize was that the starting point was too vague, and that the amount of work that was needed to implement such guide was too large.
We can, however, take a different approach this time: create a special MIGRATION.md document, and require that every breaking feature was listed there together with a short explanation on how to migrate. That way the guide would be built incrementally in small steps.
"Implementing" this issue requires:
- creating a blank document
MIGRATION.md(or however we want to call it); - updating the contributing guidelines;
- updating the PR template to mention the new document.
Might this not be a bit too soon? v1 just got released and we are focusing on not introducing any breaking changes unless really necessary or fully talked about it by the whole team, so I am not seeing the use for already having a migration guide to a v2 when we havent even released anything new on the v1?
Or am I just missing the point here?
The point here is not to get into the habit of kicking this can down the road.
If we require that every PR should include tests, examples, documentation, and migration instructions (if applicable), then by the time of the v2 release, the migration guide would be up and ready. Updating this guide at the PR time is also much easier than at any later point in time, since the change is still fresh in memory.
I think this is a pretty good idea! It will be easy to refer questions to specific lines in the migration guide then.
Hmm, thinking about this some more I don't think we should have a file that is updated in the PR, because then we will have the same problem as we did with the changelog file. Maybe we can generate this from the git log if we make sure that the squashed commit messages include this for breaking changes?
An important note to add here is that we won't strictly follow semver for major versions, we will do something more similar to how Flutter does it. So there will be need for migration docs before 2.0 too.
Hmm, thinking about this some more I don't think we should have a file that is updated in the PR, because then we will have the same problem as we did with the changelog file. Maybe we can generate this from the git log if we make sure that the squashed commit messages include this for breaking changes?
It won't be the same as with the changelog, because (hopefully) we won't be introducing breaking change with every PR. In fact, updates to the migration guide should be quite rare.
In addition, the migration guide is best to be structured logically rather than chronologically. That is, instead of "here are the changes we made in December, and here are the changes from January, etc", we should strive to have the document structured as "here are the changes to Game class, here are the changes to Effects system, etc". This is especially important if there are multiple changes that touch the same class / method.