Recommendations on how to interact with github.

[Patrick Williams]

There have been a lot of pull requests that generate a very messy patch
set sequence.  This is my recommendations on working with git(hub) to
avoid this.

Cloning a repository:
    * Create a user fork of the repository you want to work on.
        - https://github.com/openbmc/<repo> , click 'fork' in right
          corner.
    * Clone the repository.
        - git clone git at github:<user>/<repo>
    * Add original repository.
        - git remote add github git at github:openbmc/<repo>
    * Change the URL of the original repository to prevent accidental
      pushes.
        - git remote set-url --push github dont_push_to_team_repo

Starting new work:

If you have an outstanding pull request, it is best if you can frame
your addition as a separate item from your first pull request.  If you
know you are working on something entirely different, create a new
branch for the new work.  This prevents the case where you have two pull
requests in process and one pull request includes all of the other pull
request, which leads to confusion as to which pull request is suppose to
be reviewed.

    * Fetch from the team repository to make sure you are up to date:
        - git fetch github
    * Create a local branch from the team repository.
        - git checkout -b <workitem> github/master
    * ... do your work ...

Pushing work for pull request:

You should ensure your work is up-to-date before you create your pull
request.

    * Fetch from the team repository:
        - git fetch github
    * Rebase your work on top of the latest.
        - git rebase github/master
    * Push your work to a [new] branch on your github repository.
        - git push origin HEAD:refs/heads/<workitem>

Updating your pull request to fix review comments:

When you get a review comment on a specific commit, you should fix that
specific commit.  You should not create a NEW commit with review fix-ups.
We don't want to see code that didn't pass review in the team's git
history at all.

    * Checkout the branch you did the work on.
        - git checkout <workitem>
    * Make sure it is up to date with the team repository.
        - git fetch github
        - git rebase github/master
    * Do a rebase interactive to 'edit' any of the commits you need to.
        - git rebase --interactive github/master
        - The previous command will bring up an editor with a number of
          lines prefixed with 'pick'.  Any of them that you want to
          modify to fixup code reviews you should change to 'edit'.
        - You are now in the most scary part of git: a rebase.
        - Git will stop at the first commit you asked to 'edit'.
            + Edit the files you need to for the code review.
            + 'git add <files edited>'
            + 'git commit --amend'
            + 'git rebase --continue'
        - Repeat the previous step until you complete the rebase.
    * Confirm the code after the rebase still compiles and works.
    * Push to your github repository.
        - git push origin HEAD:<workitem> --force
    * Your pull request will automatically update if you have correctly
      pushed to the same branch you originally made the pull request
      from.

A note on commit messages:

I would strongly recommend reading through these two pages for advice on
what [good] commit messages should look like.

[1] https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
[2] https://wiki.openstack.org/wiki/GitCommitMessages

-- 
Patrick Williams
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20151021/88f8c976/attachment.sig>