Thirdparty: Harmonize patches to document downstream changes

[akien-mga]

Due to not having proper documentation on how to do this, various contributors have used slightly different approaches over the years, and we find it's difficult to convey what should be done in a consistent way.

I'll finally get to write such documentation, but first I'm harmonizing the way we do patches so that it can be better documented:

• Patches should be placed in a patches subfolder, with a descriptive name in kebab case, with .patch extension, starting with a four digit index to know in which order to apply them (e.g. 0001-win7-8-dynamic-load.patch).
• We no longer include // -- GODOT start -- and // -- GODOT end -- comments around our changes. The patch files should be enough to document what changes we've done.
• Patches should be the output of git diff, i.e. in Git compatible format and relative to the root of the Git repo. When using the patch command to apply them, that means using patch -p3 < path/to/patch from the thirdparty library's folder, to skip the first 3 folders from the diff paths, e.g. a/thirdparty/embree. Alternatively apply them with git apply from anywhere, or patch -p1 from the root folder of the Godot repository.
• Thirdparty libraries which have patches should have it identified in thirdparty/README.md in a "Patches:" list of the patch filenames. We identify which PR added the patch in parenthesis, so that context can be found easily without having to write it in the README (which we very rarely did). For example:

## basis_universal

- Upstream: https://github.com/BinomialLLC/basis_universal
- Version: 1.50.0 (051ad6d8a64bb95a79e8601c317055fd1782ad3e, 2024)
- License: Apache 2.0

Files extracted from upstream source:

- `encoder/` and `transcoder/` folders, with the following files removed from `encoder`:
  `jpgd.{cpp,h}`, `3rdparty/{qoi.h,tinydds.h,tinyexr.cpp,tinyexr.h}`
- `LICENSE`

Patches:

- `0001-external-zstd-pr344.patch` (GH-73441)
- `0002-external-jpgd.patch` (GH-88508)
- `0003-external-tinyexr.patch` (GH-97582)
- `0004-remove-tinydds-qoi.patch` (GH-97582)

• Patches should be generated with git diff > patches/my-patch-name.patch, and the generated patch file added to the same commit that's doing the change to thirdparty code. In other words, the process to generate a patch is:

  1. Copy unmodified thirdparty code, stage it.
  2. Re-applying pre-existing patches in the identified order, stage those changes.
  3. Make required changes to the thirdparty code, minimizing unneeded changes (style, whitespace, etc.).
  4. Generate a patch for those with git diff > patches/000x-descriptive-name.patch, stage both thirdparty code changes and the patch.
  5. Add the name of the patch in thirdparty/README.md where relevant, and with the PR number in parenthesis in the form (GH-xxxxx). If you haven't opened the PR yet, you can make an educated guess based on what's the latest issue/PR number, or amend it in after opening the PR.
  6. If relevant, repeat that workflow for unrelated changes, to try to keep each patch atomic and well described by its file name.

• When updating a thirdparty library, the process is to remove all existing files (but the patches folder), copy the new files following the thirdparty/README.md instructions, and stage that. Then start reapplying patches in order with git apply patches/0001-some-patch.patch or patch -p3 < patches/0001-some-patch.patch. If any patch fails or notifies about having to do fuzzy hunk matching, stop at that stage and rediff the patch before proceeding to the next step.

[akien-mga]

All done, should be ready to review.

[akien-mga]

FYI @Faless - I decided to rename our ENet Godot socket implementation to enet_godot.{cpp,h} instead of just godot.{cpp,h} to be more explicit.

[akien-mga]

I just restored the original code with #if 0, for documentation's sake and to reduce the risk of conflict.

[akien-mga]

This patch was missing changes from Set to RBSet done by Juan a while ago.

[akien-mga]

I reviewed each commit on GitHub and found a few issues in a couple patches, now fixed.

This should finally be ready. Once approved, I'll squash the commits.

Edit: Wait, I spotted some remaining GODOT start comments that need to be cleaned up.

Edit 2: Now it's ready, I'm happy with the current state.

[fire]

My main requirement is that GitHub tests pass. My look-over by hand will be shallow. Approved.

Thanks for getting to this. It has been a problem that's now resolved.

I suggest finding a good place to put the description's instructions for patch creation. This may be enough for a first draft of patch creation documentation for third-party software in Godot Engine.

Edited:

I have created a godot engine documentation bug godotengine/godot-docs#10591

[RandomShaper]

• We no longer include // -- GODOT start -- and // -- GODOT end -- comments around our changes. The patch files should be enough to document what changes we've done.

♥️

[akien-mga]

I squashed the commits, so this should be ready to merge.

It's not exactly critical for 4.4 but it's just a documentation update for the most part, and since it will generate conflicts for cherry-picks, I'd prefer to have 4.4.stable and 4.5-dev share the same baseline so 4.5-dev thirdparty lib updates can easily be cherry-picked to 4.4.x.

[Repiteo]

Needs a rebase

[akien-mga]

Done.

[Repiteo]

Thanks!