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. -- Paul W. Frields http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://redhat.com/ - - - - http://pfrields.fedorapeople.org/ Where open source multiplies: http://opensource.com -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
