slorber
commented
3 years ago Hey
As part of https://github.com/facebook/docusaurus/issues/5380, I'd like to encourage swizzle --wrap for most use-cases instead of swizzle --copy (ie current behavior).
I'm trying to see with Facebook how to handle versioning once v2.0 is released:
- It's likely that we'll respect semver, but at the same time we don't want to increase major to Docusaurus v15 very fast
- I think we can respect semver for
--wrap, maintaining public API surface compatibility on existing theme components - We may need to consider
--copyas a non-public API surface (ie you are on your own). I suggested we could bump the minor version (v2.1) on such internal theme breaking changes.
Even if --copy wouldn't be the recommended thing to do, we'll still need to reduce annoying updates for our users.
For now, I think we should focus on shipping swizzle --wrap and a good, explicit theme public API,
We'll figure out tooling to support swizzle --copy better later.
An idea is to build a web tool to help users upgrade their theme components highlighting the theme changes for convenient backporting, similar to the React-Native upgrade-helper website: https://react-native-community.github.io/upgrade-helper/?from=0.62.0&to=0.67.0-rc.0
I was also thinking about providing a patch system, a bit different than yours:
- store the version at which the theme file was copied (like, in a file comment:
// version: 2.1.3) - have a cli like
docusaurus swizzle upgrade-copy theme-classic theme/NavBar: Docusaurus would compute a diff from2.1.3to current version and attempt to apply a patch automatically
💥 Proposal
We can make swizzle something similar to
yarn patch: it lets you change a file and only records the diff. During an upgrade, if there's a "merge conflict", it asks you to reswizzle the component.I have no idea how heavy the implementation would be on our side, or if there are packages we can use
Have you read the Contributing Guidelines on issues?
Yes