openstack-doc-core team mailing list archive

[Lorin Hochstein <lorin@xxxxxxxxxxxxxxxxxx>]

On May 14, 2012, at 9:43 AM, Anne Gentle wrote:

> How do you all think this affects docs? My thoughts:
> 
> - Docs can document a master branch and know what features are going into it.

If we are documenting features that haven't made it into the master nova branch yet, we should annotate this in our docs. Something that says, "this chunk of text describes the behavior in the 'foo' branch". We need to track when these hit master and update these tags accordingly. 

> - We still need experts who know about the subsystems:
> OpenStack APIs
> 
> EC2 API
> virt
> libvirt driver
> xenapi driver
> vmware driver
> networking
> volumes
> scheduler
> RPC
I don't know how to get around this expert deficit issue.  I'd be happy having "doc liaisons" for every subsystem. Basically, designated nova developers who can recognize when a new feature lands in a subsystem branch that needs to be documented. The liaison would then file a doc bug with a pointer to the feature. At least we could track what we're missing that way.

Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com



> APIs are a bit different in governance of the content created for those - since they're in separate repositories. However, the api.openstack.org site is contained within openstack-manuals. Plus we haven't done much to document EC2 and OpenStack.
> 
> Would like some input on whether we should adjust any processes going forward. How do we as a doc team support this? Any changes?
> Anne
> 
> ---------- Forwarded message ----------
> From: Thierry Carrez <thierry@xxxxxxxxxxxxx>
> Date: Mon, May 14, 2012 at 7:51 AM
> Subject: Re: [Openstack] Nova subsystem branches and feature branches
> To: openstack@xxxxxxxxxxxxxxxxxxx
> 
> 
> James E. Blair wrote:
> > Vish, Thierry, and I spent some time together this week at UDS trying to
> > reconcile their needs and your suggestions.  I believe Thierry is going
> > to write that up and send it to the list soon.
> 
> While at UDS we took some time to discuss a subsystem branch models that
> would work for Vish (PTL/developer), Jim (CI/infra) and me (release
> time). We investigated various models and came up with "Vish's
> supercombo subsystem model" (see model 5 at the bottom of
> http://wiki.openstack.org/SubsystemsBranchModel for a graph).
> 
> In this model:
> 
> * You have a "master" branch which contains release-ready features and
> bugfixes. Milestones are cut directly from it.
> 
> * Subsystem branches with area experts are used wherever possible. The
> subsystem maintainer should maintain this branch so that it can directly
> be merged into master when "ready" (all or nothing). Subsystem
> maintainers are allowed to propose a merge commit to master.
> 
> * Bugfixes get proposed directly to master
> 
> * Features can be directly proposed to master, although they should be
> redirected to a subsystem branch when one exists for that area
> 
> * Only features that are release-ready should be accepted into master.
> Final approval of merges on master will therefore be limited to the
> corresponding project release team.
> 
> * Milestones are directly cut from master. A couple of days before each
> milestone, we will have a soft freeze during which only bugfixes are merged
> 
> * Between the last milestone and RC1, a soft freeze is enforced during
> which only bugfixes are merged (can last for a couple weeks)
> 
> * In order to limit the master freeze, at RC1 and until release, a
> specific release branch is cut from master. That specific release branch
> directly gets release-critical (targeted) bugfixes, and gets merged back
> into master periodically.
> 
> Benefits of this model:
> * We enable subsystems, which for larger projects let people specialize
> on an area of the code and avoids having to be an expert in all things
> * Subsystems become a staging ground for features that are not release-ready
> * Avoid painful cherry-picks between RC1 and release
> * Release part of the model can be used on smaller projects without
> necessarily adopting the rest of the model (subsystem and release team
> approval on master)
> 
> Pain points:
> * For smaller projects, you have to use subsystems if you want a staging
> ground for features (though you could also advertise given feature
> branches). Those projects could certainly use an "experimental"
> subsystem and adopt that model, though.
> * You still need project-core reviewers on master branch for bugfixes
> and features directly proposed
> * Master is not always open, there are soft-frozen periods (could be
> seen as a benefit to get people to focus on bugfixes though)
> 
> --
> Thierry Carrez (ttx)
> Release Manager, OpenStack
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
> 
> -- 
> Mailing list: https://launchpad.net/~openstack-doc-core
> Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp