Skip to content

Commit

Permalink
update tutorials for new git tools
Browse files Browse the repository at this point in the history
  • Loading branch information
@kpedro88 @gudrutis
kpedro88 authored and gudrutis committed Aug 21, 2018
1 parent ec93cbb commit fcf4e7e
Show file tree
Hide file tree
Showing 2 changed files with 104 additions and 54 deletions.
38 changes: 20 additions & 18 deletions tutorial-collaborating-with-peers.md
View file
Expand Up @@ -35,30 +35,32 @@ Proposing changes happens by creating a Pull Request from a given repository to
the official one (also referred as official-cmssw), this is documented in the
[Proposing changes to CMSSW tutorial](tutorial.html).

Sharing changes between peers is done instead by merging a remote branch in
your local workarea. Such a branch is not necessarily associated to a pull
Sharing changes between peers is done instead by checking out or merging a remote branch in
your local workarea. Such a branch is not necessarily associated with a pull
request nor necessarily coming from the official CMSSW repository, effectively
allowing groups of people to collaborate with each other before a topic is
proposed for official inclusion in CMSSW.

### git cms-merge-topic
### Developing on top of another topic branch

While checking out a topic can be done with the standard git commands: `git
fetch` + `git merge`, `git pull`, we provide an helper script, called
If your new topic branch requires changes from another topic branch to work (e.g. a pull request that hasn't been merged yet),
you can use `cms-checkout-topic` to recreate the working area used to develop the other topic branch, and then
make your changes on top of it.

git cms-merge-topic
Notes and caveats for this approach:
* You need to determine what release or IB was used as the base for the other topic branch using `git log` or the GitHub history view
(or by asking the other developer).
* If you have to rebase your branch, it is important to specify the "old base" of your branch as the first commit before your changes,
i.e. the other developer's last commit. (This could happen if e.g. the other developer rebases the other branch, or if a conflict arises
once you have submitted the PR for your branch.) See the rebasing tutorial [Resolving conflicts & porting features](tutorial-resolve-conflicts.html)
for more information.

which removes some of the boiler-plate required. This command can be used for
two different use cases:
### Developing on top of multiple topic branches

- Merging a pull request:

git cms-merge-topic <pull-request-id>

- Merging a remote branch:

git cms-merge-topic <github-user>:<branch-name>

the latter command will use the official-cmssw remote in case no github
username is provided.
If your new topic branch requires changes from multiple other topic branches to work,
it is easiest to use `git cms-merge-topic` to combine all the other branches in your working area.

However, this should only be done on a temporary basis. If you plan to make a PR, you should eventually
create a "clean" branch that contains just your commits and no uses of `cms-merge-topic`.
You can do this by rebasing or cherry-picking (again, see the rebasing tutorial [Resolving conflicts & porting features](tutorial-resolve-conflicts.html)
for more information.)
120 changes: 84 additions & 36 deletions tutorial-resolve-conflicts.md
View file
Expand Up @@ -13,13 +13,31 @@ redirect_from:
One of the greatest advantages of _git_ is that it is much smarter at handling
conflicts between different contribution to the same repository. In particular
it automatically handles the case of two parallel developments, both changing
the same package in orthogonal manner. As smart as it can be, however,
the same package in orthogonal ways. As smart as it can be, however,
git does not know about the mass of the Higgs or how to resolve conflicts where two
people modified the same line in different ways. This latter case is however
automatically detected by GitHub, which will point out that your changes cannot
be merged automatically.

This tutorial will show you how to resolve the latter problem using the `git rebase` command.
This tutorial will show you how to resolve the latter problem using the `git rebase` command
and several CMS-specific wrapper commands.

### Uses of CMS commands

* `git cms-rebase-topic`:
* moving a branch to a new IB/release
* rebasing a branch to resolve merge conflicts
* `git cms-checkout-topic`:
* recreating a working area
(in case it got deleted or corrupted, but the base CMSSW release still exists)
* working on top of another topic branch
(see tutorial [Collaborating with peers](tutorial-collaborating-with-peers.html))
* preparing to build a CMSSW patch release
* setting up for advanced use of `git rebase`
* `git cms-merge-topic`:
* *testing* a branch or PR
* combining multiple patches in a private recipe/release
* ***NOT*** to be used when developing PRs!

### Overview of rebasing

Expand Down Expand Up @@ -86,31 +104,11 @@ Very important note: ***NEVER*** use `git cms-merge-topic` to resolve conflicts
This can introduce hundreds of duplicate commits. Release and package managers have the right
and the responsibility to reject such broken pull requests immediately.

Let's set up your working area with the source code corresponding to the unmergeable branch.
(It is important in this step to do an "unsafe checkout" with the `-u` option, because
the unmergeable branch is based on a different release of CMSSW than your current area.)
Let's use the simple `cms-rebase-topic` command to deal with the unmergeable branch in your working area.
```
git cms-checkout-topic -u kpedro88:Unmergeable8025
git cms-rebase-topic kpedro88:Unmergeable8025
```

For safety, you can make a temporary branch to backup the current state.
(Experience developers may choose to ignore this step.)
```
git checkout -b Unmergeable8025-backup
git push my-cmssw Unmergeable8025-backup
git checkout Unmergeable8025
```

Now you can start the rebase:
```
git rebase --onto CMSSW_8_0_26 CMSSW_8_0_25 Unmergeable8025
```
This follows the pattern `git rebase --onto [new base] [old base] [branch]`.
Remember, `[new base]` and `[old base]` can be commit hashes rather than tags.
If you are working in an integration build (IB) that has expired (so the tag is no longer available),
or if you lost your original working area and forgot which release was your old base,
you can use `git log` to find the hash of the latest commit before your changes, and proceed normally.

This will fail with a message like:
```
First, rewinding head to replay your work on top of it...
Expand Down Expand Up @@ -193,6 +191,17 @@ git rebase --continue
This means the commit entitled "add new PU scenario" has been modified to avoid the conflict
in the new base release CMSSW_8_0_26.

If you look at the current list of branches with `git branch`, you will see that a branch named "..._backup" has been added by default:
```
CMSSW_8_0_X
* Unmergeable8025
Unmergeable8025_backup
from-CMSSW_8_0_26
kpedro88/Unmergeable8025
rebase-attempt
```
This backup branch contains the state of the branch before the rebase was done.

### Finalizing the updates

The temporary branch is now up-to-date with the current release. This means that it is safe to
Expand Down Expand Up @@ -221,31 +230,46 @@ scram b
```
Here, you do a "safe" checkout, which automatically checks out any dependent packages as well.

### Recovering from a bad rebase (or merge)

If something went wrong during your rebase, or if you accidentally used `cms-merge-topic` and your PR has been rejected,
you should go back to your working area and use the automatically-created backup branch:
```
git push -f my-cmssw [branch]_backup:[branch]
```
where `[branch]` is the name of your branch.

If you have made subsequent commits in the broken branch, you may want to keep the broken branch so you can `cherry-pick` the new commits later:
```
git push -f my-cmssw [branch]:[branch]_broken
```

Once you have recovered the previous state of your branch, please follow the approved procedures as outlined here.

### More advanced options

If you find that the rebased code does not compile or run correctly because of a mistake
during the rebase process, you can make an additional commit to fix the problem.
If you want access to options of `git rebase` that are not provided in `git cms-rebase-topic`,
you can use `git cms-checkout-topic -u` and then use the `git rebase` command.
(The `-u` option avoids calling `cms-checkdeps` before the branch is rebased.)

If you find that the rebased code does not compile or run correctly because of a mistake
during the rebase process, you can make an additional commit to fix the problem.
However, advanced users may instead try the `git rebase --interactive` option,
which allows you to edit the existing commits. This means that you can solve any problems
in-place and preserve the linear development history.

### The above is all great stuff but I need a quick recipe!

This is the most concise and general recipe to rebase your branch, resolve conflicts, and update your PR.
This is the most concise recipe to rebase your branch, resolve conflicts, and update your PR.
You can also use this recipe to move to a new IB. (If there are no conflicts, the `cms-rebase-topic` command
will automatically call `cms-checkdeps -a` when it finishes.)

```
cmsrel [NEW_RELEASE]
cd [NEW_RELEASE]/src
cmsenv
git cms-checkout-topic -u [user]:[my-branch]
<optional backup>
git checkout -b [my-branch]-backup
git push my-cmssw [my-branch]-backup
git checkout [my-branch]
git cms-rebase-topic [user]:[my-branch]
git rebase --onto [NEW_RELEASE] [OLD_RELEASE] [my-branch]
<resolve conflicts as needed>
git cms-checkdeps -a
Expand All @@ -259,13 +283,37 @@ git push -f my-cmssw [my-branch]
Any pull request for a new feature must first be submitted to the open development branch (always the `master` branch).
Some features may need to be backported to older CMSSW versions, e.g. to fix bugs for data-taking or add options for MC production.

If we needed to backport the change from the above example branch `kpedro88:Unmergeable8025` to the `CMSSW_7_1` series,
the exact same rebasing procedure can be followed. The "new base" in this case is the latest release `CMSSW_7_1_26`
If we needed to backport the change from the above example branch `kpedro88:Unmergeable8025` to the `CMSSW_7_4` series,
the exact same rebasing procedure can be followed. The "new base" in this case is the latest release `CMSSW_7_4_16`
(instead of `CMSSW_8_0_26`, as we used in the example). That's right; rebasing can work in any "direction".

However, it is necessary to provide more information when porting a PR between branches, since different branches
may have different commits beyond the changes you have made in your topic branch.

In the case of a backport, you should make a copy of your original topic branch and rebase the copy,
because you will submit a separate PR.

Example:
```
scram project CMSSW_7_4_16
cd CMSSW_7_4_16/src
cmsenv
git cms-rebase-topic --old-base CMSSW_8_0_25 kpedro88:Unmergeable8025
<resolve conflicts>
git branch -m Unmergeable8025_7416
```

Notice that you have to specify the "old base" of the branch with the `--old-base` (or simply `-o`) option. This does several things:
* Uses the "old base" to determine which packages you have changed, to avoid checking out unneeded packages
with `cms-addpkg`. (This works with any `cms-...-topic` command).
* Uses a more explicit form of of the `git rebase` command: `git rebase --onto [new base] [old base] [branch]`. (You can also specify
the new base with the `--new-base` or `-n` option; by default, it uses `$CMSSW_VERSION`.)

Remember, `[new base]` and `[old base]` can be commit hashes rather than tags.
If you are working in an integration build (IB) that has expired (so the tag is no longer available),
or if you lost your original working area and forgot which release was your old base,
you can use `git log` or the GitHub history view to find the hash of the latest commit before your changes, and proceed normally.

### Cherry-picking commits

There are a few cases where you might want to individually apply commits from one branch to another branch, rather than rebasing.
Expand Down

0 comments on commit fcf4e7e

Please sign in to comment.