====== Git / Evergreen development discussion notes ======

Git tracks commits - includes metadata such as description, signed-off-by lines, etc along with the actual code patches

===== Key #1 to workflow =====

  * If git complains about a non-fast-forward update, DO NOT FORCE A PUSH!
    * **ACTION**: Prevent non-fast-forward updates on main topic branches (branches that have been shared with the world) (**DONE**)
  * **ACTION**: Adopt naming convention for branches that should not be pulled from
    * For example, ''wip/foobar'' = work in progress = pull at your own risk
    * lp####### for a branch for a Launchpad bug
      * dbs would start with ''dbs/lp1234567'' for trunk; when happy, push to ''bugs/lp1234567'' for trunk
      * then backport to ''dbs/rel_2_0/lp1234567'' and push to ''bugs/rel_2_0/lp1234567''
 
===== Central repository as collection point =====

  * We would like to promote the use of a central git repository for both main and non-main trees
  * To set up a new non-main tree generally requires interested party to send the git maintainer a pubkey & email address
  * We would like to be reasonably open - but must assert that any committed code is a) relevant to Evergreen and b) DCO'ed and licensed under GPL v2-or-later
  * In the new regime, a committer would be someone who has the ability to push to master branch and create tags
  * Possible to give multiple people the ability to push into a single branch (eg. collaborative topic branch like MARC-must-die, QA staging branch)
  * **ACTION**: Galen will manage the git server (at least to begin with). **DONE**
  * **ACTION**: Invite tsbere to join Galen in administering gitolite **UPDATE** tsbere invited and has accepted.  **DONE, tsbere is active**
  * **ACTION**: ILS-Contrib needs to move to central repository (as an ILS-contrib tree) **UPDATE 2011-05-14 start with website, which is being set up as a separate repo**

===== Workflow - squashing vs. maintaining all the ugly =====

  * Goals are to:
    - Make the patches comprehensible (one logical unit per patch - like a bullet point in a slide)
    - Enable the patches to make sense as a series (get rid of the 'gah' commits)
  * One option: **Interactive rebase** at point that QA is satisfied
  * Please continue to separate whitespace commits from substantive commits
  * Get used to the notion of having code sit in the topic branch for some time to be reviewed / tested
  * ''tig'' is an ncurses-based interface for browsing the commit history

===== For git-format-patch patches sent to the list / attached to Launchpad =====

  * ''git-format-patch'' is much nicer as it tracks metadata such as author, etc, rather than having to do it manually
  * Create a local branch
  * Use ''git am'' to apply the patch
  * Test
    * If the patch is perfect, push it to a public branch
    * If the patch is 90% good, but needs fixes; commit the patch as-is and commit a follow-up patch to clean it up (this avoids merge conflicts when the patch contributor pulls from master subsequently)
  * Patch wrangler?
  * **ACTION**: Follow-up with Chris Sharp on git.evergreen-ils.org server.  **UPDATE 2011-05-02** Request sent to Chris Sharp; awaiting date for when GPLS IT can create the VM. **DONE**

===== Rough plan =====

  - git-svn clone to seed the master repository (OpenSRF and ILS at the same time)
    * Bring tags along - but only for SVN tags, not one per revision (''git-svn'' applies a git-svn-id with the revision number) **DONE**
  - Gather committers' public keys **UPDATE 2011-05-14: underway; some committers are either on vacation or are apparently inactive**
  - Test repository (go or no go)
  - Pick a weekend for cutting over (at least a week after release: Galen suggests Saturday, May 14)  **DONE for Evergreen and OpenSRF**

===== Things that need to be done: =====

  * Modify Web site references to SVN
    * Contributing document (update references, git-format-patch) **UPDATE 2011-05-14: well under way**
    * Policies for being added to the repo server
    * Suggested naming conventions **UPDATE 2011-05-14: underway, see #evergreen logs**
    * Statement on Evergreen interpretation of Signed-off-by **DONE**
  * Wiki references to SVN **UPDATE 2011-05-14: major references updated; still a number of minor references to clean up**
  * Check codebase for SVN references (such as staff client installer auto build ID) **UPDATE 2011-05-14; direct references removed; phasefx and tsbere looking at the build ID issue**
  * DIG manual references
  * Blog post / mailing list **DONE**
  * Make SVN Trac page say "read-only" for each gitted repository **DONE**
  * Teach continuous integration server about git **DONE**
  * Freshmeat **DONE** / Ohloh **DONE** / Launchpad **master branch replaced SVN trunk, but seems to be a limit of a single branch that can be tracked? Also, need to retarget all "trunk" issues to "master"?**
  * (Per comment by Jeff Godin on 2011-05-02) set up master to send updates to Evergreen commits mailing list. **DONE tsbere++**