Re: [edk2] An unkempt git guide for edk2 contributors and maintainers

2016-02-13 Thread Laszlo Ersek 
On 02/12/16 02:09, Laszlo Ersek wrote:
> [...]

This guide is now available in the TianoCore wiki, at

https://github.com/tianocore/tianocore.github.io/wiki/Laszlo's-unkempt-git-guide-for-edk2-contributors-and-maintainers

with a few topical fixups (I applied a suggestion from Paolo, thx), and
more formatting / usability improvements. (Click the "revisions" link if
you are interested.)

In particular, all steps were extended with anchors, and all references
to steps became intra-page hyperlinks. (While the gray I have in my hair
doubled.) This should allow readers to jump to referenced steps quickly,
and also to return to the referer with the browser's Back button.

Kudos to Jordan for the initial MarkDown conversion (which required
renumbering the Maintainer workflow steps and references)!

Laszlo
___
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

Re: [edk2] An unkempt git guide for edk2 contributors and maintainers

2016-02-12 Thread Ryan Harkin 
Hi Laszlo,

Great writeup!  I learned a few tips, for sure.

On 12 February 2016 at 01:09, Laszlo Ersek  wrote:
> Disclaimer
> ==
>
> This is a quick and dirty, simplified and slightly modified description
> of my own edk2 workflow with git. It expressly defers to any upcoming
> git workflow documentation on the wiki. It doesn't try to be generic,
> focuses only on GNU/Linux (that's what I use). It will not go into many
> details about git; if you are interested, you'll have to research those
> concepts on the web yourself.
>
> Also, this is very specific to edk2. Other projects have different
> workflows.
>
>
> Contributor workflow
> 
>
> (01) Create an account on GitHub.
>
> (02) Enable SSH authentication for your account.
>
>https://help.github.com/articles/generating-an-ssh-key/
>
>  When completing this step, you should end up with a new keypair
>  under ~/.ssh/, for example:
>
>id_rsa_for_github
>id_rsa_for_github.pub
>
>  and the following stanza in your ~/.ssh/config:
>
>Host github.com
>  User  git
>  IdentityFile  ~/.ssh/id_rsa_for_github
>
> (03) Fork the following repository on GitHub into your own GitHub
>  account, using the GitHub web GUI:
>
>https://github.com/tianocore/edk2/
>
>  (My personal fork is at
>
>https://github.com/lersek/edk2/
>  )
>
> (04) Clone the official edk2 repository to your local computer:
>
>cd some-appropriate-directory
>git clone https://github.com/tianocore/edk2.git
>
> (05) Implement the following git settings for your local clone, i.e.,
>  while standing in your local edk2 directory (these steps don't need
>  customization):
>
>git config am.keepcr  true
>git config am.signoff true
>git config cherry-pick.signofftrue
>git config color.diff true
>git config color.grep auto
>git config commit.signoff true
>git config core.abbrev12
>git config core.pager cat
>git config core.whitespacecr-at-eol
>git config diff.algorithm patience
>git config diff.ini.xfuncname '^\[[A-Za-z0-9_.,   ]+]'
>git config diff.renames   copies
>git config format.signoff false
>git config notes.rewriteRef   refs/notes/commits
>git config sendemail.chainreplyto false
>git config sendemail.thread   true
>
> (06) Also implement the following -- they need customization:
>
>git config sendemail.smtpserver FQDN_OF_YOUR_LOCAL_SMTP_SERVER
>git config user.email   "Your Email Address"
>git config user.name"Your Name"
>
> (07) Create a file called "tianocore.template" somewhere outside your
>  edk2 clone, with the following contents (remove leading
>  whitespace). Note that the last line requires customization.
>
>[empty line]
>[empty line]
>Contributed-under: TianoCore Contribution Agreement 1.0
>Signed-off-by: Your Name 
>
> (08) Standing in your edk2 clone, implement the following setting
>  (requires customization):
>
>git config commit.template \
>  FULL_PATHNAME_OF_FILE_CREATED_IN_LAST_STEP
>

Now, I wish I'd known about this before I went to the bother of
creating a prepare-commit-msg hook (attached for your amusement at the
wasted effort)

The concept of using a hook might be more flexible in theory, but in
practice, a template is perfect for most people.


> (09) Open the file
>
>.git/info/attributes
>
>  (create it if it doesn't exist), and add the following contents
>  (with the leading whitespace removed):
>
>*.efi -diff
>*.EFI -diff
>*.bin -diff
>*.BIN -diff
>*.raw -diff
>*.RAW -diff
>*.bmp -diff
>*.BMP -diff
>*.dec diff=ini
>*.dsc diff=ini
>*.dsc.inc diff=ini
>*.fdf diff=ini
>*.fdf.inc diff=ini
>*.inf diff=ini
>
> (10) Create a file called "edk2.diff.order" somewhere outside your local
>  clone, with the following contents (removing the leading
>  whitespace):
>
>*.dec
>*.dsc.inc
>*.dsc
>*.fdf
>*.inf
>*.h
>*.vfr
>*.c
>
> (11) Add your own fork of edk2 that lives on GitHub as a *remote* to
>  your local clone:
>
>git remote add -f --no-tags \
>  YOUR_GITHUB_ID \
>  g...@github.com:YOUR_GITHUB_ID/edk2.git
>
> (12) At this point you are ready to start developing. Refresh your local
>  master branch from the upstream master branch:
>
>git checkout master
>git pull
>
>  The first command is extremely important. You should only run "git
>  pull" while you are standing on your

Re: [edk2] An unkempt git guide for edk2 contributors and maintainers

2016-02-12 Thread Laszlo Ersek 
On 02/12/16 13:46, Ryan Harkin wrote:
> Hi Laszlo,
> 
> Great writeup!  I learned a few tips, for sure.

Thanks!

> On 12 February 2016 at 01:09, Laszlo Ersek  wrote:

>> (08) Standing in your edk2 clone, implement the following setting
>>  (requires customization):
>>
>>git config commit.template \
>>  FULL_PATHNAME_OF_FILE_CREATED_IN_LAST_STEP
>>
> 
> Now, I wish I'd known about this before I went to the bother of
> creating a prepare-commit-msg hook (attached for your amusement at the
> wasted effort)
> 
> The concept of using a hook might be more flexible in theory, but in
> practice, a template is perfect for most people.

I do have two hook scripts (post-checkout and post-merge) that update my
tags file automatically. So hooks are indeed powerful. But the amount of
comments in your hook script implies you had to think way too much for
that Contributed-under tag! :)

>> (23) Now we'll format the patches as email messages, and send them to
>>  the list. Standing in the root of your edk2 directory, run the
>>  following (note that the "-O" option needs customization: please
>>  update the pathname to the file created in step (10)):
>>
>>rm -f -- *.patch
>>
>>git format-patch   \
>>  --notes  \
>>  -O"/fully/qualified/path/to/edk2.diff.order" \
>>  --cover-letter   \
>>  --numbered   \
>>  --subject-prefix="PATCH v1"  \
>>  --stat=1000  \
>>  --stat-graph-width=20\
>>master..implement_foo_for_bar_v1
>>
>>  This command will generate an email file for each one of your
>>  commits. The patch files will be numbered. The file numbered 
>>  is a *cover letter*, which you should edit in-place:
>>
>>  - in the "Subject:" line, summarize the goal of your series,
>>
>>  - in the message body, describe the changes on a broad level,
>>
>>  - *reference*, by complete URL, the "implement_foo_for_bar_v1"
>>branch in your personal GitHub repo -- the one that you pushed in
>>step (22),
>>
>>  - finally, add *all* of the Cc: tags to the cover letter that you
>>used across all of the patches. This will ensure that even if a
>>maintainer is involved in reviewing one or two of your patches
>>across the series, he or she will get a copy of your cover
>>letter, which outlines the full feature or bugfix.
>>
>> (24) Time to mail-bomb the list! Do the following:
>>
>>  git send-email \
>>--suppress-cc=author \
>>--suppress-cc=self   \
>>--suppress-cc=cc \
>>--suppress-cc=sob\
>>--to=edk2-devel@lists.01.org \
>>*.patch
>>
>>  This command might ask you about sending the messages in response
>>  to another message (identified by Message-Id). Just press Enter
>>  without entering anything.
>>
>>  You might want to run the command first with the --dry-run
>>  parameter prepended.
>>
>>  The messages will be posted to the list only, and to the
>>  maintainers that you Cc'd explicitly in the commit messages.
>>
>>  Once the messages are sent, you can remove the local patch files
>>  with:
>>
>>rm -f -- *.patch
>>
> 
> Is there an advantage to your workflow?
> 
> I appreciate that there are many ways to do the same task, but I find
> it more efficient to use "git send-email
> master..implement_foo_for_bar_v1 [various options]" because it gives
> me 1 step in 1 command rather than 2 steps in 3 commands.
> 
> I can see that a v2 of a patch series would be easier if I stored the
> *.patch file rather than deleted it.

For me, separating the formatting and mailing steps has a few advantages:

- I get to look at the exact, formatted patch message. I like to verify
how the diffstat looks, if the notes (from git-notes) are there, and so on.

- As you say, I preserve the patch files. (In fact I have one big,
concatenated mbox file per posting per series.) I don't just preserve
the patch files / series file until the work gets merged -- I preserve
my postings *forever*. Occasionally it allows me to grep for stuff I
vaguely recall from my patches, very quickly and targeted-ly.

- Reiterating the blurb in the v(n+1) cover letter is indeed one use case.

- I have an additional, personal check that I like to do before posting
v(n+1). I compare the mbox files (the concatenated series mboxes)
between v(n) and v(n+1). This gives me a kind of "interdiff".

I mainly use it to verify that I have listed *all* inter-version code
changes in the per-patch git-notes sections. I like my git-notes to be
complete; that's when they help the reviewer best.

Thanks
Laszlo

Re: [edk2] An unkempt git guide for edk2 contributors and maintainers

2016-02-12 Thread Paolo Bonzini 


On 12/02/2016 02:09, Laszlo Ersek wrote:
> (23) Now we'll format the patches as email messages, and send them to
>  the list. Standing in the root of your edk2 directory, run the
>  following (note that the "-O" option needs customization: please
>  update the pathname to the file created in step (10)):
> 
>rm -f -- *.patch
> 
>git format-patch   \
>  --notes  \
>  -O"/fully/qualified/path/to/edk2.diff.order" \
>  --cover-letter   \
>  --numbered   \
>  --subject-prefix="PATCH v1"  \
>  --stat=1000  \
>  --stat-graph-width=20\
>master..implement_foo_for_bar_v1

You can add

   git config diff.orderFile "/fully/qualified/path/to/edk2.diff.order"

to step (10) instead of adding -O.

Also you can add

   git config --global alias.format-series "format-patch --notes --cover-letter 
--numbered --stat=1000 --stat-graph-width=20"

to step (05) and simplify the above to

   git format-series --subject-prefix="PATCH v1" master..

> 
>  git send-email \
>--suppress-cc=author \
>--suppress-cc=self   \
>--suppress-cc=cc \
>--suppress-cc=sob\
>--to=edk2-devel@lists.01.org \
>*.patch

Same here.  You can add more "git config" commands to step (05),
particularly

   git config send-email.to = edk2-devel@lists.01.org

and simplify this to

   git send-email *.patch

(Not sure why you're adding the Why the "--suppress-cc").

Paolo
___
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

Re: [edk2] An unkempt git guide for edk2 contributors and maintainers

2016-02-12 Thread Laszlo Ersek 
On 02/12/16 19:50, Paolo Bonzini wrote:
> 
> 
> On 12/02/2016 02:09, Laszlo Ersek wrote:
>> (23) Now we'll format the patches as email messages, and send them to
>>  the list. Standing in the root of your edk2 directory, run the
>>  following (note that the "-O" option needs customization: please
>>  update the pathname to the file created in step (10)):
>>
>>rm -f -- *.patch
>>
>>git format-patch   \
>>  --notes  \
>>  -O"/fully/qualified/path/to/edk2.diff.order" \
>>  --cover-letter   \
>>  --numbered   \
>>  --subject-prefix="PATCH v1"  \
>>  --stat=1000  \
>>  --stat-graph-width=20\
>>master..implement_foo_for_bar_v1
> 
> You can add
> 
>git config diff.orderFile "/fully/qualified/path/to/edk2.diff.order"
> 
> to step (10) instead of adding -O.

I didn't know about "diff.orderFile", despite -O... always annoying me.
Which tells me something is wrong, because I have pretty low tolerance
for stuff in git annoying me, so I think I must have researched a
permanent setting for -O... at some point, and failed. Let me check again.

... Indeed, "diff.orderFile" was added to git between v1.8.5 and v1.9.0.
I'm on RHEL-7, and RHEL-7 ships (in RHEL-7.2.z, at the moment)
git-1.8.3.1-6.el7.

> Also you can add
> 
>git config --global alias.format-series "format-patch --notes 
> --cover-letter --numbered --stat=1000 --stat-graph-width=20"
> 
> to step (05) and simplify the above to
> 
>git format-series --subject-prefix="PATCH v1" master..

Oh I definitely use a bunch of aliases, and indeed "format-series" is
one of them. However, in this guide I deliberately avoided using aliases
-- I intended to show the direct commands, and allow users to pack them
into scripts or aliases.

Also, "--stat=1000 --stat-graph-width=20" is very specific to edk2 (due
to the incredibly long directory and file names it uses -- otherwise the
diffstats would truncate a bunch of pathnames on the left with ...), so
I think these options are not the best for --global.

> 
>>
>>  git send-email \
>>--suppress-cc=author \
>>--suppress-cc=self   \
>>--suppress-cc=cc \
>>--suppress-cc=sob\
>>--to=edk2-devel@lists.01.org \
>>*.patch
> 
> Same here.  You can add more "git config" commands to step (05),
> particularly
> 
>git config send-email.to = edk2-devel@lists.01.org

That's right.

> 
> and simplify this to
> 
>git send-email *.patch
> 
> (Not sure why you're adding the Why the "--suppress-cc").

I like when my upstream posts go only to the To: address, and to
explicit commit message Cc:'s.

Thanks!
Laszlo
___
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

[edk2] An unkempt git guide for edk2 contributors and maintainers

2016-02-11 Thread Laszlo Ersek 
Disclaimer
==

This is a quick and dirty, simplified and slightly modified description
of my own edk2 workflow with git. It expressly defers to any upcoming
git workflow documentation on the wiki. It doesn't try to be generic,
focuses only on GNU/Linux (that's what I use). It will not go into many
details about git; if you are interested, you'll have to research those
concepts on the web yourself.

Also, this is very specific to edk2. Other projects have different
workflows.


Contributor workflow


(01) Create an account on GitHub.

(02) Enable SSH authentication for your account.

   https://help.github.com/articles/generating-an-ssh-key/

 When completing this step, you should end up with a new keypair
 under ~/.ssh/, for example:

   id_rsa_for_github
   id_rsa_for_github.pub

 and the following stanza in your ~/.ssh/config:

   Host github.com
 User  git
 IdentityFile  ~/.ssh/id_rsa_for_github

(03) Fork the following repository on GitHub into your own GitHub
 account, using the GitHub web GUI:

   https://github.com/tianocore/edk2/

 (My personal fork is at

   https://github.com/lersek/edk2/
 )

(04) Clone the official edk2 repository to your local computer:

   cd some-appropriate-directory
   git clone https://github.com/tianocore/edk2.git

(05) Implement the following git settings for your local clone, i.e.,
 while standing in your local edk2 directory (these steps don't need
 customization):

   git config am.keepcr  true
   git config am.signoff true
   git config cherry-pick.signofftrue
   git config color.diff true
   git config color.grep auto
   git config commit.signoff true
   git config core.abbrev12
   git config core.pager cat
   git config core.whitespacecr-at-eol
   git config diff.algorithm patience
   git config diff.ini.xfuncname '^\[[A-Za-z0-9_.,   ]+]'
   git config diff.renames   copies
   git config format.signoff false
   git config notes.rewriteRef   refs/notes/commits
   git config sendemail.chainreplyto false
   git config sendemail.thread   true

(06) Also implement the following -- they need customization:

   git config sendemail.smtpserver FQDN_OF_YOUR_LOCAL_SMTP_SERVER
   git config user.email   "Your Email Address"
   git config user.name"Your Name"

(07) Create a file called "tianocore.template" somewhere outside your
 edk2 clone, with the following contents (remove leading
 whitespace). Note that the last line requires customization.

   [empty line]
   [empty line]
   Contributed-under: TianoCore Contribution Agreement 1.0
   Signed-off-by: Your Name 

(08) Standing in your edk2 clone, implement the following setting
 (requires customization):

   git config commit.template \
 FULL_PATHNAME_OF_FILE_CREATED_IN_LAST_STEP

(09) Open the file

   .git/info/attributes

 (create it if it doesn't exist), and add the following contents
 (with the leading whitespace removed):

   *.efi -diff
   *.EFI -diff
   *.bin -diff
   *.BIN -diff
   *.raw -diff
   *.RAW -diff
   *.bmp -diff
   *.BMP -diff
   *.dec diff=ini
   *.dsc diff=ini
   *.dsc.inc diff=ini
   *.fdf diff=ini
   *.fdf.inc diff=ini
   *.inf diff=ini

(10) Create a file called "edk2.diff.order" somewhere outside your local
 clone, with the following contents (removing the leading
 whitespace):

   *.dec
   *.dsc.inc
   *.dsc
   *.fdf
   *.inf
   *.h
   *.vfr
   *.c

(11) Add your own fork of edk2 that lives on GitHub as a *remote* to
 your local clone:

   git remote add -f --no-tags \
 YOUR_GITHUB_ID \
 g...@github.com:YOUR_GITHUB_ID/edk2.git

(12) At this point you are ready to start developing. Refresh your local
 master branch from the upstream master branch:

   git checkout master
   git pull

 The first command is extremely important. You should only run "git
 pull" while you are standing on your local master branch that
 tracks (and never diverges from) the upstream master branch.

 These commands will fetch any new commits from upstream master, and
 fast-forward your local tracking branch to the new HEAD.

(13) Create and check out a topic branch for the feature or bugfix that
 you would like to work on. The topic branch name requires
 customization of course.

   git checkout -b implement_foo_for_bar_v1 master

(14) Make sure you have the build environment set up:

   source edk2setup.sh
   make -C "$EDK_TOOLS_PATH"

(15) Implement the next atomic, logical step in your feature or bugfix.
 Test that

Re: [edk2] An unkempt git guide for edk2 contributors and maintainers

2016-02-11 Thread Laszlo Ersek 
On 02/12/16 02:05, Laszlo Ersek wrote:

> (16) Add your changes gradually to the staging area of git (it is called
>  the "index"):
> 
>git add -p
> 
>  This command will ask you interactively about staging each separate
>  hunk. See the manual for "git add".

I forgot to name two more commands here -- I've been now reminded of
them by Erik's and Jordan's updates to
:

- In order to stage a completely new file, use

  git add pathname-of-new-file

- In order to stage the removal of a file, use

  git rm pathname-of-file-to-remove

Thanks
Laszlo
___
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel