Skip to content

ci: reorder custom branches documentation #696

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
scpeters wants to merge 1 commit into
base: master
Choose a base branch
from
Open

ci: reorder custom branches documentation #696

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 44 additions & 44 deletions common/ci.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,50 +185,6 @@ The following methods can be used by maintainers to re-trigger builds:
* On the top-right of a build inside the 'Actions' tab of GitHub, click
`Re-run jobs`. Note that this button sometimes mysteriously disappears.

### Testing pull requests with custom tooling branches

As noted above, the [gzdev](https://github.com/gazebo-tooling/gzdev),
[homebrew-simulation](https://github.com/osrf/homebrew-simulation), and
[gazebodistro](https://github.com/gazebo-tooling/gazebodistro) tooling repositories
each contain metadata about dependencies for each package on Ubuntu, macOS,
and Windows, respectively. If you wish to test a pull request with a custom
branch of one of these tooling repositories, you can do this by creating
branches with the same name that starts with `ci_matching_branch/` on both the
tooling repository and the repository to be tested.

#### Example: testing with an additional dependency on macOS

In [gz-math#361](https://github.com/gazebosim/gz-math/pull/361), a fix for
gz-math's python bindings on macOS was proposed, but `pybind11` was not yet
a dependency of the `gz-math` homebrew formulae. To test this pull request
with pybind11 installed in the macOS CI machines,
identical branch names `ci_matching_branch/math_scripting` were used for
[gz-math#361](https://github.com/gazebosim/gz-math/pull/361) and
[homebrew-simulation#1793](https://github.com/osrf/homebrew-simulation/pull/1793)
which allowed the gz-math macOS CI build to include the new dependency.

#### Example: testing with a source build of a custom branch of a dependency on macOS

To determine whether changes in gz-math and sdformat were the cause of gz-sim
test failures documented in
[osrf/buildfarm-tools#67 (comment)](https://github.com/osrf/buildfarm-tools/issues/67#issuecomment-2232120738),
the `gz-math8` and `sdformat15` formulae were modified so that the primary
`url` field contains the URL of their respective git repositories, along with a
`branch` field indicating the branch name to be tested. The `gz-math8` formula
was [modified to use the `scpeters/revert_606` branch](https://github.com/osrf/homebrew-simulation/blob/6bdfaea6c9b5a30fed163c619e1f398b31937514/Formula/gz-math8.rb#L4)
(corresponding to [gz-math#609](https://github.com/gazebosim/gz-math/pull/609)),
and the `sdformat15` formula was [modified to use the `scpeters/revert_1458` branch](https://github.com/osrf/homebrew-simulation/blob/6bdfaea6c9b5a30fed163c619e1f398b31937514/Formula/sdformat15.rb#L4)
(corresponding to [sdformat#1459](https://github.com/gazebosim/sdformat/pull/1459)).
These changes to formulae were commited to the
`ci_matching_branch/revert_math_graph_init` branch (see
[osrf/homebrew-simulation@6bdfaea6](https://github.com/osrf/homebrew-simulation/pull/2701/commits/6bdfaea6c9b5a30fed163c619e1f398b31937514)).
To test gz-sim with these branches of gz-math and sdformat, a trivial change
to the gz-sim README was made in a branch with matching name
`ci_matching_branch/revert_math_graph_init`, and a draft pull request
([gz-sim#2482](https://github.com/gazebosim/gz-sim/pull/2482))
was opened to trigger CI builds. The homebrew build used the matching
branch of homebrew-simulation and built against the intended branches.

### Custom branches

Maintainers can manually trigger builds for custom branches without opening pull
Expand Down Expand Up @@ -315,6 +271,50 @@ different jobs:
to run only gz-transport8 tests, the `--packages-select gz-transport8` can
be added to the default options.

### Testing pull requests with custom tooling branches

As noted above, the [gzdev](https://github.com/gazebo-tooling/gzdev),
[homebrew-simulation](https://github.com/osrf/homebrew-simulation), and
[gazebodistro](https://github.com/gazebo-tooling/gazebodistro) tooling repositories
each contain metadata about dependencies for each package on Ubuntu, macOS,
and Windows, respectively. If you wish to test a pull request with a custom
branch of one of these tooling repositories, you can do this by creating
branches with the same name that starts with `ci_matching_branch/` on both the
tooling repository and the repository to be tested.

#### Example: testing with an additional dependency on macOS

In [gz-math#361](https://github.com/gazebosim/gz-math/pull/361), a fix for
gz-math's python bindings on macOS was proposed, but `pybind11` was not yet
a dependency of the `gz-math` homebrew formulae. To test this pull request
with pybind11 installed in the macOS CI machines,
identical branch names `ci_matching_branch/math_scripting` were used for
[gz-math#361](https://github.com/gazebosim/gz-math/pull/361) and
[homebrew-simulation#1793](https://github.com/osrf/homebrew-simulation/pull/1793)
which allowed the gz-math macOS CI build to include the new dependency.

#### Example: testing with a source build of a custom branch of a dependency on macOS

To determine whether changes in gz-math and sdformat were the cause of gz-sim
test failures documented in
[osrf/buildfarm-tools#67 (comment)](https://github.com/osrf/buildfarm-tools/issues/67#issuecomment-2232120738),
the `gz-math8` and `sdformat15` formulae were modified so that the primary
`url` field contains the URL of their respective git repositories, along with a
`branch` field indicating the branch name to be tested. The `gz-math8` formula
was [modified to use the `scpeters/revert_606` branch](https://github.com/osrf/homebrew-simulation/blob/6bdfaea6c9b5a30fed163c619e1f398b31937514/Formula/gz-math8.rb#L4)
(corresponding to [gz-math#609](https://github.com/gazebosim/gz-math/pull/609)),
and the `sdformat15` formula was [modified to use the `scpeters/revert_1458` branch](https://github.com/osrf/homebrew-simulation/blob/6bdfaea6c9b5a30fed163c619e1f398b31937514/Formula/sdformat15.rb#L4)
(corresponding to [sdformat#1459](https://github.com/gazebosim/sdformat/pull/1459)).
These changes to formulae were commited to the
`ci_matching_branch/revert_math_graph_init` branch (see
[osrf/homebrew-simulation@6bdfaea6](https://github.com/osrf/homebrew-simulation/pull/2701/commits/6bdfaea6c9b5a30fed163c619e1f398b31937514)).
To test gz-sim with these branches of gz-math and sdformat, a trivial change
to the gz-sim README was made in a branch with matching name
`ci_matching_branch/revert_math_graph_init`, and a draft pull request
([gz-sim#2482](https://github.com/gazebosim/gz-sim/pull/2482))
was opened to trigger CI builds. The homebrew build used the matching
branch of homebrew-simulation and built against the intended branches.

## Development

All the infrastructure for our CI is in the
Expand Down
Loading