Splitting version changes

Over on the commits list Hal pointed out that

These things, and the license headers, should really be committed separately.
There are several different ways to separate a patch file into separate commits
(and at least several of us here who have experience doing surgery on patches).
Feel free to ask for advice (might as well do it on the dev list:
it is a common problem), and you shall receive it.

So, Hal, please enlighten us.

-- Jim

James Cownie <james.h.cownie@intel.com>
SSG/DPD/TCAR (Technical Computing, Analyzers and Runtimes)
Tel: +44 117 9071438

I am unfamiliar with any common practice to separate license headers,
copyright notices or similar into an independent commit. When such things
are broadly changed I could see that being independent, but new code should
just come with the headers in tact (and correct). I think I'm not getting
all the context, but please do feel free to clarify if there is some
precedent for this.

From: "C Bergström" <cbergstrom@pathscale.com>
To: "James H Cownie" <james.h.cownie@intel.com>
Cc: openmp-dev@dcs-maillist2.engr.illinois.edu
Sent: Wednesday, October 8, 2014 3:24:31 AM
Subject: Re: [Openmp-dev] Splitting version changes

Over on the commits list Hal pointed out that

> These things, and the license headers, should really be committed
> separately.
> There are several different ways to separate a patch file into
> separate commits
> (and at least several of us here who have experience doing surgery
> on patches).
> Feel free to ask for advice (might as well do it on the dev list:
> it is a common problem), and you shall receive it.

So, Hal, please enlighten us.

I am unfamiliar with any common practice to separate license headers,
copyright notices or similar into an independent commit. When such
things are broadly changed I could see that being independent, but
new code should just come with the headers in tact (and correct). I
think I'm not getting all the context, but please do feel free to
clarify if there is some precedent for this.

You're correct, I'm referring only to the large-scale updating of existing files.

-Hal

From: "James H Cownie" <james.h.cownie@intel.com>
To: openmp-dev@dcs-maillist2.engr.illinois.edu
Cc: "Hal Finkel (hfinkel@anl.gov)" <hfinkel@anl.gov>
Sent: Wednesday, October 8, 2014 2:51:44 AM
Subject: Splitting version changes

Over on the commits list Hal pointed out that

> These things, and the license headers, should really be committed
> separately.
> There are several different ways to separate a patch file into
> separate commits
> (and at least several of us here who have experience doing surgery
> on patches).
> Feel free to ask for advice (might as well do it on the dev list:
> it is a common problem), and you shall receive it.

So, Hal, please enlighten us.

I'll preface this by saying that there may yet be better ways, but here's what I've used...

First, I'd be remiss were I to neglect to mention that emacs has a really-nice patch-editing mode. Here's some documentation:
  https://www.gnu.org/software/emacs/manual/html_node/emacs/Diff-Mode.html
and if you really need to do some non-trivial surgery directly on a patch file, I've not found a better alternative (I normally use vim, but this is the one thing for which I use emacs). To use this for splitting, you'd make several copies of the patch file and, in each, delete the non-relevant parts from each.

Next, I'll strongly recommend that you use 'git svn' to manage your interaction with the upstream subversion repository instead of using svn directly. I should mention that, since the OpenMP repository does not have much history, you can just do a full clone:
  git svn clone https://llvm.org/svn/llvm-project/openmp/trunk openmp-trunk
if you try this with LLVM or Clang, it will take a *long* time because it tries to replay the remote repository one commit at a time. For this, add -r HEAD so that it will just start at the latest commit. There's lots of information out there on using git svn, including:
  http://llvm.org/docs/GettingStarted.html#for-developers-to-work-with-git-svn
  http://git-scm.com/book/en/Git-and-Other-Systems-Git-and-Subversion

To the topic at hand, once you're using git locally, you can read "Splitting up commits the easy way" (http://cbx33.github.io/gitt/afterhours5-1.html) which talks about how to use git's interactive staging feature to split up a large patch file and commit it in separate pieces. This can be done both using command-line tools and also using 'git gui' if you'd prefer the GUI-based interface.

If you'd like more information and/or help on any of these, please feel free to ask.

Thanks again,
Hal

> From: "James H Cownie" <james.h.cownie@intel.com>
> To: openmp-dev@dcs-maillist2.engr.illinois.edu
> Cc: "Hal Finkel (hfinkel@anl.gov)" <hfinkel@anl.gov>
> Sent: Wednesday, October 8, 2014 2:51:44 AM
> Subject: Splitting version changes
>
> Over on the commits list Hal pointed out that
>
> > These things, and the license headers, should really be committed
> > separately.
> > There are several different ways to separate a patch file into
> > separate commits
> > (and at least several of us here who have experience doing surgery
> > on patches).
> > Feel free to ask for advice (might as well do it on the dev list:
> > it is a common problem), and you shall receive it.
>
> So, Hal, please enlighten us.

I'll preface this by saying that there may yet be better ways, but here's what I've used...

First, I'd be remiss were I to neglect to mention that emacs has a really-nice patch-editing mode. Here's some documentation:
  https://www.gnu.org/software/emacs/manual/html_node/emacs/Diff-Mode.html
and if you really need to do some non-trivial surgery directly on a patch file, I've not found a better alternative (I normally use vim, but this is the one thing for which I use emacs). To use this for splitting, you'd make several copies of the patch file and, in each, delete the non-relevant parts from each.

Next, I'll strongly recommend that you use 'git svn' to manage your interaction with the upstream subversion repository instead of using svn directly. I should mention that, since the OpenMP repository does not have much history, you can just do a full clone:
  git svn clone https://llvm.org/svn/llvm-project/openmp/trunk openmp-trunk

We have a git mirror too: http://llvm.org/git/openmp.git

Changes should really be based on top of that rather than a fresh
git-svn clone. :slight_smile:

if you try this with LLVM or Clang, it will take a *long* time because it tries to replay the remote repository one commit at a time. For this, add -r HEAD so that it will just start at the latest commit. There's lots of information out there on using git svn, including:
  http://llvm.org/docs/GettingStarted.html#for-developers-to-work-with-git-svn
  http://git-scm.com/book/en/Git-and-Other-Systems-Git-and-Subversion

To the topic at hand, once you're using git locally, you can read "Splitting up commits the easy way" (http://cbx33.github.io/gitt/afterhours5-1.html) which talks about how to use git's interactive staging feature to split up a large patch file and commit it in separate pieces. This can be done both using command-line tools and also using 'git gui' if you'd prefer the GUI-based interface.

If you'd like more information and/or help on any of these, please feel free to ask.

I find that people are always surprised when they learn about 'git add
-p', which I heartily recommend to everyone who uses git regularly.
It's essential for creating logical patches.

Jim, I'd be happy to help as well, just send me an email and I'll be
able to suggest some ways to make things better.

Excellent, thanks. I thought git should be the answer, and I should have looked for an emacs-mode, since I've been using it since 1984 or so. (Back when the joke was that it stood for "Eight Megabytes And Constantly Swapping").

-- Jim

James Cownie <james.h.cownie@intel.com>
SSG/DPD/TCAR (Technical Computing, Analyzers and Runtimes)
Tel: +44 117 9071438