swizzle --patch

[Josh-Cena]

💥 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

[slorber]

Hey

As part of #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 --copy as 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 from 2.1.3 to current version and attempt to apply a patch automatically