HOWTO update your code across a large whitespace change

From Nsnam
Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

When maintaining code outside of the main ns-3-dev tree, such as for pull requests, or for project forks, users periodically want to rebase their out-of-tree code against ns-3-dev 'master' branch as it evolves.

Usually this is straightforward and relatively painless, such as:

 $ git checkout master
 $ git pull
 $ git checkout my-new-feature-branch
 $ git rebase master

If there are merge conflicts, the rebase is stopped and you have a chance to manually fix the affected file, perform a `git add` to add it back, and then perform 'git rebase --continue'.

However, during the ns-3.36 to ns-3.37 release cycle, the maintainers are making large-scale changes to clean up code formatting, whitespace, and syntactic issues. This means that if you have some code that is branched from master, and you try to rebase across these large-scale changesets, the rebase may be very painful and changes to address whitespace are mixed in with the typical rebasing that may be needed due to technical changes in master branch.

Let's look at the change for trimming trailing whitespace that were introduced on June 5, 2022. From the git log:

 commit b6a5ee8151d63ffbe03f338a7e408cc556eb7330
 Author: Tom Henderson <tomh@tomh.org>
 Date:   Sun Jun 5 21:01:11 2022 -0700
     Run utils/trim-trailing-whitespace.py on codebase
 commit 7c47d8af081a951da53f29b303a792af87e40bc1
 Author: Eduardo Almeida <enmsa@outlook.pt>
 Date:   Thu Jun 2 20:22:53 2022 +0100
     doc: Fix indentation on coding-style.rst

The bottom commit (7c47d8af) was the first commit; it introduced the file 'utils/trim-trailing-whitespace.py' for fixing any trailing whitespace. The top commit (b6a5ee81) was the subsequent commit that actually made all of the whitespace changes to the codebase to bring it into compliance.

One recommended way to minimize (but not necessarily avoid) rebasing pain is to follow this strategy:

1) rebase your out-of-tree code to the commit just before the large change. That is, rebase your code on master commit 7c47d8af.

2) next, rebase your out-of-tree code to the next commit. That is, rebase (again) on master commit b6a5ee8a.

3) perform any further rebases (to even later commits on master) in the usual way.

4) it is a good idea to run 'utils/trim-trailing-whitespace.py' on all of your out-of-tree code regularly once you are past commit b6a5ee81 (maybe your IDE will do this for you automatically)

This strategy makes sure that when you are dealing with reconciling your out-of-tree changes with master, in step 2), you are only dealing with trailing whitespace cleanup and won't miss some other important merge issue.

Here is a way that you can implement the above, using a couple of temporary branches:

 $ git checkout master
 $ git checkout -b before-formatting 7c47d8af
 $ git checkout master
 $ git checkout -b after-formatting b6a5ee81
 $ git checkout my-feature-branch
 $ git rebase before-formatting

In working out the above rebase, any conflicts will *not* involve the whitespace change.

Conflicts are resolved one-by-one, by adding the file that is fixed and calling to continue rebase:

 $ git add ...
 $ git rebase --continue

Next, after that rebase is completed, proceed with the whitespace-related commit:

 $ git rebase after-formatting

Here, it may be messy to clean up (some or many of your patches may no longer apply cleanly), but the conflicts should be limited to these trailing whitespace differences.


 $ git add ...
 $ git rebase --continue

Next, you can continue to rebase all the way to the tip of ns-3-dev/master:

 $ git rebase master

Any of these conflicts would not be whitespace-related.

You can delete these temporary branches when finished:

 $ git branch -D before-formatting
 $ git branch -D after-formatting