Tutorial: How to align or update the Physics system with upstream

[diegoferigo]

In order to implement some of the gym-ignition features, we had to vendor the Physics system with our own.

In the past, we started with the files that were upstream, and then, every alignment, took commit after commit (usually are not many) and replicate them on our vendored files. In the past few weeks, a lot of changes hit upstream, and the manual replication became time consuming and error prone.

This issue describes the new process I thought to keep the vendored system updated.

In a standalone PR, for aligning with upstream follow all the steps, for updating the vendored system follow 5-6.

1. Replace all the sources of the scenario/src/plugins/Physics with the updated upstream version making sure to select the correct branch. The table contains the link to the upstream folder history and the commit used in the last alignment.
2. Commit the unmodified files.
3. Cherry pick the commits from the table below.
4. Solve potential conflicts.
5. If there are conflicts or modifications, create a new commit squashing the Custom Physics features commit with the new edits.
6. Update the table data.
7. In order to minimize the git history size, squash and merge the PR. The commit will show only the real modifications of the alignment.

This way, conflicts are handled with git and they can be solved nicely.

Branch	Aligned with	Cherry-pick
main (Fortress)	gazebosim/gz-sim@4c35f6c	514532d 2a57f5e

I also considered the other way: generating a patch from upstream by diffing two commits, but it turned out being a more difficult process. What described here is easier and it ensures that we don't forget pieces.

[FirefoxMetzger]

Wouldn't this be better located (and easier to find) inside the Discussions tab? https://github.com/robotology/gym-ignition/discussions/categories/tutorials

[diegoferigo]

I often find these piece of information scattered in multiple places:

• Issues
• Wiki
• CONTRIBUTING.md
• ...

Before enabling discussions, we were using issues just because we're used to. Now that we have discussion, I agree that it seems the best location. One drawback is that there are not (yet) cross references between issues/pr and discussions, though afaik they are a planned feature that will come at one point.