Re: [boost] [Git] Documentation for Git and Modular Boost conversion

Subject: Re: [boost] [Git] Documentation for Git and Modular Boost conversion
From: Julian Gonggrijp (j.gonggrijp_at_[hidden])
Date: 2012-12-08 20:43:18

Beman Dawes wrote:

> We are starting to pull together documentation for the Git and Modular
> Boost conversion.
> 
> https://svn.boost.org/trac/boost/wiki/WikiStart#GitandModularBoost
> 
> Comments and corrections welcome!
> 
> I'm particularly interested in unanswered questions you have after
> reading these initial docs.

I'm very excited to see this plan take form. My compliments to the 
people who are making this happen.

Browsing through the wiki pages linked from that section, a few things 
caught my attention.

wiki/ModCvtSvn2Git [1] states

> Each individual Boost library's public repository will contain a 
> single branch, "master", that corresponds to branches/release in 
> Subversion.

As I seemed to recall that the modularized Boost would adopt GitFlow, 
I was surprised by the suggestion that a library's public repository 
would not be allowed (or at least not required) to have a "develop" 
branch corresponding to the Subversion "trunk". Indeed when I opened 
wiki/StartModWorkflow [2] it turned out that the wiki pages don't 
internally agree on this issue yet:

> An unusually simple, single developer library would have only the 
> permanent *develop* and *master* branches that are required for all 
> Boost libraries.

Furthermore the bullet list at the top of [1] seems to suggest that 
the new Git repositories will not keep track of any history; only the 
list item dedicated to the old Svn repo mentions "full history". I 
believe this to be partly due to an inaccuracy, because the individual 
library repos will contain /branches/ which supposedly will hold all 
commits made to those brances. This is also further explained in [2].

Another reason might be (IIUC) that after the initial conversion, the 
individual library repos will start with only a clean copy of the 
latest state on the Svn repo. Nonetheless I believe the current 
wording on the wiki page can be needlessly alarming to the less 
gitflow-enlightened reader, because it may seem to suggest that it 
still won't record history /after/ the initial conversion.

While wiki/ModCvtSchedule [3] may be alpha, the schedule seems 
ambitious enough that I think it would be wise to get all library 
maintainers ready for take-off as soon as possible. Even if you don't 
really plan to have library maintainers start beta testing the Git 
repos next week as the schedule suggests, I think about *now* is the 
time to make a global announcement on this mailing list that 
developers will need to install Git and familiarise themselves with it 
sometime soon. I believe an exact date is not needed to license such 
an announcement.

For wiki/Git/GitHome [4] I would like to suggest two additions:
 - Add git-flow [5] to the "Installing Git" list.
 - Add GitImmersion [6] to the "Learning to use Git" list.

Hope this helps!
-Julian

----------
[1] https://svn.boost.org/trac/boost/wiki/ModCvtSvn2Git
[2] https://svn.boost.org/trac/boost/wiki/StartModWorkflow
[3] https://svn.boost.org/trac/boost/wiki/ModCvtSchedule
[4] https://svn.boost.org/trac/boost/wiki/Git/GitHome
[5] https://github.com/nvie/gitflow/wiki/Installation
[6] http://gitimmersion.com/