[OpenAFS-devel] Git/gerrit basics (Windows)

[Mickey Lane]

Thanks Jeffrey.

My comments mixed in with the stuff below...

> -----Original Message-----
> From: Jeffrey Altman [...]
> 
> Mickey Lane wrote:
> > Git/gerrit basics (Windows)
> >
> > I'd like to submit two trivial changes for the kdfs branch. They're
> > only appropriate to that branch. My main goal is really to learn the
> > git/gerrit process.
> 
> Please be aware that the entire src/WINNT/afsrdr/kernel tree is going
> to be replaced in the near future.
> 

Understood. If my update gets lost it's not that big a deal. Learning the
process is the thing here.

> > I plan to make one change, commit and submit. Then make the second
> > change and repeat the process.
> >
> > Some really basic questions:
> >
> > #1
> >
> > My two changes don't have anything to do with each other but by
> > following the above process, do I establish a dependency so that
> > the 1st change must be applied (approved?) before the 2nd?
> 
> Create each change in its own branch that tracks the remote branch
> you are basing them off of.   Commit each change to its own local
> branch and push the change to gerrit from there.
>

I'll do

	Git checkout origin/master
	git pull (since I have not modified anything yet)
	git checkout -b my-name-for-fix-1 origin/openafs-windows-kdfs-ifs-branch
	Edit 3 or 4 files
	git commit <something TBD wrt the message>
	review
	git push

and wait for the outcome of change #1 before doing anything with #2.

General questions wrt "each change in its own branch"

Suppose the goal is to fix 20 groups of compile warnings in diverse
parts of the code. Would you create 20 branches? Do these branches
have a finite lifespan?

Suppose I create 20 branches, submit the changes and the changes are
adopted without issue. How does this get cleaned up?

If 10 of these groups were say 'signed/unsigned mismatch', could you
put them under one change even if they were in widely different
parts of the code?


> > #2
> >
> > The phrase "must not end with a full stop" is confusing to Windows
> > users. (This one anyway)
> 
> a "full stop" is a period.

Heh. Sometimes we forget to think of the obvious. I must admit though
that its been a while since I've seen a period used to end what amounts
to several paragraphs.

> 
> > If I make a text file (a.txt) with the above as a guide (on Windows,
> > it'll have <carriage return><line feed>) and supply it to my commit
> > command (in the bash window from msysGit):
> >
> >                 git commit -F a.txt
> 
> I cannot promise that git will strip the CRs.  If you do not specify
> -F git.exe will start the default editor with a template file which
> will be LF only.

For Windows-only people, using vi (or whatever) is pretty painful.

If I make the file using Notepad and the commit becomes corrupted
as a result of the <carriage return><line feed> situation, is there a
clean way to fix the mess?

I haven't tried any of this yet. Anyone know what msysGit thinks
should be the editor? Is there a way to change it to something simple?

> 
> > (Minor comment wrt the web page - it took me some time to realize
> > that the above text - under the heading 'upload to gerrit' - is
> > actually part of the git commit activity and doesn't really have
> > anything to do with upload. I had assumed it was something added
> > via a gerrit form presented at the time of commit. Perhaps add
> > some text to put it in context?)
> 
> Changes are not submitted to gerrit by using a web browser.  They are
> pushed to gerrit using the "git push" command which in turn uses the
> ssh client you configured to communicate securely with gerrit's clone
> of the repository.

I figured that out. My comment was an attempt to suggest that this is
not clear to people doing this the 1st time and that some different
wording might help avoid the confusion.

> 
> > #3
> >
> > I have given the Gerrit server my SSH public key but I'm not sure how
> > msysGit and/or PuTTY and/or ???? is supposed to be configured to make
> > all this work.
> 
> I recommend you use the OpenSSH instance that ships with msysGit.
> The SSH public key you generated should have a matching private key
> in the ~/.ssh directory.  The ~/.ssh/config file needs to be configured
> as specified on the OpenAFS GitDevelopers wiki page.
> 

A footnote or maybe a separate page for Windows users would be a big
help here. The "~/.." notation is foreign to Windows and there is no
~/.ssh directory after a msysGit install & build.

If, like me, you already have SSH keys, it's not at all clear what
you're supposed to do with them. Using msysGen, I generated another set
and discovered where msysGen wants them (it's C:\Documents and
Settings\<username>\.ssh). It would also be useful to note the use of
the -C switch to set the user name in the keys since the default
is login-name@machine-name on a Windows box which almost never equates
to anything useful.

> > #4
[...snip...]

> > #5
> >
> > If the push completes without apparent error, is that the end of the
> > process?
> 
> The submit is now in gerrit where it can be reviewed.  Comments can be
> applied.  Verification can be specified.  If it all looks good, it will
> be submitted.  If it needs work, you will need to update the commit and
> resubmit it to the same gerrit issue.  This is hopefully explained well
> enough in the GitDevelopers wiki page.
> 

I'm very impressed with the GitDevelopers wiki page. It does a good job
of giving just the right amount of information. My only complaint, and I
realize I probably represent 1 percent of the readers, is that it doesn't
do much for Windows users who have no *nix background. I'm not sure what,
if anything, could be done about that but I'll think about it for a while.

> Jeffrey Altman

Mickey.