Re: Guide branching [resend]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 





On 11/02/10 14:43, Paul W. Frields wrote:
On Thu, Feb 11, 2010 at 12:15:30PM +1000, Chris Curran wrote:
  
   Having some mail client issues. Resending.

   On 02/11/2010 11:17 AM, Susan Lauber wrote:

     The time rapidly approaches when we need to start updating the guides
     for a new version.  In this example - start work on F13 version of the
     guides.
     Basically - I wanted to know where to start contributing changes
     intended for the F13 version on guides. And where to point new
     contributors as well.

     In the meeting tonight, a discussion started about branching
     philosophies.
     #action laubersm Bring branching topic to docs list to decide how we
     want to do this going forward, and record it for posterity.

     I have looked at a couple of guides in git.  They seem to have a master,
     F11, F10, etc, and various F??-tx branches.
     I think we generally agree that the F??-tx branches are for the
     translation teams.
     The rest seems to indicate a need for a F12 branch and then master
     becomes F13.
     But when should the F12 branch appear so that work on F13 can begin?

     I did not look at all the guides - there may be other schemes in use
     already.

     So I see 2 major parts to the question:
     1. Is this the branching scheme that works best for Fedora Docs group
     and guides?
        What are the alternatives?
        pros/cons?  etc

   The alternative is not branching. Just to build and forget. This isn't the
   kindest approach and goes against some of the theory of open source.

   I would say branch at release. We do not have the resources to maintain
   old forks of books but we should keep the source for posterity.
    
I think this is the most rational choice too, and mimics what we do
elsewhere in Fedora.  Granted, the No Frozen Rawhide process we're
trying for F13/F14 changes that a bit, but the reasons why that's
changed aren't really relevant for docs if history is a guide.

  
     2. WHEN do we branch?

   I would argue for at the date of translation string freeze. Only critical
   updates (like an error which causes users to delete their root partition)
   found in translation should get updated after that point.
    
Most of the world over, a branch happens at the time you need to
indicate "This bunch of code/docs/stuff is not going to change
drastically from here on out, and will be treated as stable."
Translation seems as good a way to anchor that as any, and better than
some others.  (Release day isn't a horrible choice, but it's kind of
arbitrary when you think about this in terms of "when is this stuff
considered stabilized.")

  
     Should the F12 branch been made at release of F12 so that master moves
     to the next version right away?

   It should be made at translation. I would argue for having master to just
   keep going. This allows for continual development. I know how much some
   people *hate* RAD, agile or SCRUM approaches but unless I get three major
   contributors that is the only feasible approach to take. Fedora
   continually changes during a release. It is not the same Fedora by the end
   of the 6 months when the next one starts coming out and the documentation
   is usually out of date for most interfaces of developed projects.

   I would argue here for a master/lastest branch and then legacy branches.
    
Sounds right to me.  The nice thing about git projects is how cheap
the branches are.  You can collaborate with people on a
"new-section-on-empathy" branch that is ugly and broken at various
times, and when it's all done, merge it cleanly back to "master" in
the middle of the cycle.

  
     If so, how do we handle mid release updates to a guide?

   We should have a master or latest branch and some method for pushing more
   frequent updates. The present method, with the CVS/php/voodoo monstrosity
   is a failure. It takes days to push a book and translations. This is not a
   conductive environment for updating documentation. I know someone will
   respond with the "Zikula is coming" or some such but this is really
   holding us back. Is there anything stopping Infrastructure just giving us
   limited access to puppet so we can push updates in a more timely and
   effective fashion?

   Until something changes in Infrastructure do not expect *any* mid release
   updates, ever. It is too much work and takes a fanaticism and commitment
   which I certainly lack. Masochism is not everyone's idea of a good time.
    
If I was part of the Docs team leadership and I really wanted mid
release updates, I'd expect to make more of an effort to make specific
assignments for those updates to new people who are showing up asking
to help.  (It'd be good to have more active mentorship of those folks
on the list, period, but that's a side topic.)  For instance, I might
assign someone to look at a specific guide, and confirm it is accurate
for the existing release -- pointing that person at the project's
Fedora Hosted wiki page with instructions on how to get the material,
build, and read/test it.

I'm not saying I think mid-release updates are intrinsically valuable,
just making a suggestion for people to consider iff. mid-release
updates are important to them.

  
     Should master stay the current version until the next release alpha? 
     Which is about now.
     Or even longer?

   Master should just go with the latest and greatest. I think this is one of
   Fedora's strengths which the Documentation Project should latch onto and
   hold for dear life. We can channel the energy which most people, including
   myself, love about Fedora and open source; the life which drives continual
   change. People want to document new features and technologies far more
   than they want to do many other things. We need to channel this energy
   into our docs. We need people working on documenting the latest and
   greatest bits of code. Master should be as fast as the writers want to
   ride the lightning, if that is Rawhide, so be it. I am presently intending
   to go this direction with the Virtualization Guide.
    
+1.  I think this is the sanest approach with a six-month release
cycle for a number of reasons -- not just for reasons of people-time
when it comes to maintenance, but also when it comes to coordination
and tracking effort.



My only question is, who are the Guides aimed at, primarily? I would've thought that most of the people who turn to the guides when they have a problem would be those who are new to Fedora, maybe even to Linux in general; this group is more likely to be using the current stable release, rather than Rawhide.  If the bulk of the 'readership' falls into this category, might there not be a case for prioritising the correction and upkeep of the guides for the current stable release, over and above trying to document every new bit of code as soon as it hits Rawhide?

This isn't necessarily to say that master shouldn't "go with the latest and greatest" - and I realise that we don't have the people-time to document every new feature as it comes as well as maintain a perfectly accurate and complete legacy branch for the stable release - but I guess I'd want to know that the work I put into Fedora docs is actually useful to people who come to the guides looking for help, at the time at which they need it. If most of those people happen to be using Rawhide, then perhaps we need to make it easier for them to access the up-to-date documentation mid-cycle. However, I'm willing to bet that a fair old chunk of guide readers are current stable release users who need accurate information for the system they just installed from their live cd or whatever.

Regards,
Nathan

-- 
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe: 
https://admin.fedoraproject.org/mailman/listinfo/docs

[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux