[OPEN-ILS-DEV] commiting documentation changes from the branches of others into Evergreen repo

[Dan Scott]

On Mon, Jun 11, 2012 at 01:49:04PM -0400, Soulliere, Robert wrote:
> Hi Developers,
> 
> I have tested committing a change for the docs folder in the code
> repository. However I am a bit fuzzy on committing changes from the
> branches of other into the main repo. For example, bshum made did some
> asciidoc cleanup here:
> 
> http://git.evergreen-ils.org/?p=working/Evergreen.git;a=commit;h=af19fa6419e5328058338cada40b42a44b0522de
> 
> and I want to merge the changes into the repo. I don't think the
> changes have been merged yet?

Actually, I think they were pushed to master, based on the shortlog at
http://git.evergreen-ils.org/?p=Evergreen.git;a=summary (or running "git
log" against a current copy of master).

It looks like you used "git merge" to merge Ben's branch into your copy
of the master repository, then committed the merge of that branch with
your own commit message of "Merge remote branch 'origin' into
documentation_test", then pushed your documentation_test branch to
master.

> What appropriate steps are used to make
> that happen? Do I need to set up my own working branch, merge bshum's
> changes into my branch and then merge my branch into the master repo,
> or can I merge bshum's branch directly into the master branch?

Generally, the process that we've been following for the code is to use
"git cherry-pick" to sign-off on each commit that we want to bring into
the master branch, rather than "git merge". As documented at
http://evergreen-ils.org/dokuwiki/doku.php?id=dev:git#guidelines_for_contributors
under the "Signing off on one or more commits" section, the process is
basically:

1. git checkout -b new_branch origin/master
2. git cherry-pick -s <commit-hash>
3. <test the changes to ensure docs still build>
4. git push origin new_branch:master

The main difference to note is the push to "origin" instead of
"working"; "origin" is where the canonical set of code lives. If you
want to push your branch out to the working repository so that others
can check your efforts first for things like proper sign-offs / comments
/ everything works, then you push to the "working" repo in your own user
directory -- e.g.

git push working new_branch:user/rsoulliere/new_branch

Also note that "new_branch" should be something meaningful, like
"dos_to_unix_linefeeds", so that a few months later if you're wondering
what the branch was for you don't have to wade through a bunch of
"quick_test" "fix_bug" generic branch names (speaking from experience
here!)

Also also note that when the docs get merged into the rel_2_2 branch, to
apply changes there you would checkout the new branch against
"origin/rel_2_2" instead of "origin/master" in step 1.

If you're ever feeling unsure about any of these steps, feel free to
throw questions at #evergreen - there's plenty of us who will be happy
to help you out!
 
> Also, I am concerned about keeping track of these branched changes to
> ensure that they do not slip through the cracks as we get more
> contributors. Is there a recommended strategy for keeping up with
> contribution branches.

I think this was mentioned elsewhere, but the best practice (again,
keeping in sync with what we're doing for code) is probably to file a
bug at http://bugs.launchpad.net/evergreen and tag it "documentation" so
that you can generate lists of doc bugs that have not yet made it to
"Fix committed" or "Fix released" status.