drafts section of the juju docs

[Mark Mims]

On 06/20/2012 02:38 PM, Gustavo Niemeyer wrote:
> On Wed, Jun 20, 2012 at 5:26 PM, Mark Mims<mark.mims at canonical.com>  wrote:
>> I'm asking if developers can "spec review" and subsequently develop against
>> an entire branch instead of a file in the drafts folder in trunk
> (...)
>> - submits branch for code review
>> - upon approval, merges into trunk
>> - docs for this feature show up on the website
> This doesn't work because documentation often precedes feature
> development, and follows the review process. That's one of the reasons
this process does allow docs (and spec approval) to precede development

> why it's good to have them in separate branches. The other is that we
> have two implementations running in parallel today, so arguably that
> documentation is for both.
Ah, good point... it's a lot of work to map docs against two separate 
projects.  What features described in the docs are implemented in go at 
any given time?  It seems like that problem's solved by keeping the docs 
with the code.

What we've effectively done is overloaded the documentation to include 
the notion of feature approval.  I.e., what does it mean for a feature 
spec to be approved?  It means it's been accepted into drafts on docs 
trunk.  That's what leads to potential leakage of spec'd feature docs.  
Can we capture feature approval somewhere else?  i.e., tags on the 
feature branch or bug?

If we do keep up the current process, we need to please make sure that 
MPs include notes to move docs from drafts to release locations.  If we 
do this at code merge time, then we just have to deal with the fact that 
the docs will be out of sync with the code until the next ppa build 
and/or distro release, but at least the developers are the ones updating 
the docs from draft status and not ~charm-contributors.

Generally, we also need to figure out when to release the docs.  ppa 
build time?  distro release time?  Note that they're currently released 
every ten minutes or so from lp:juju/docs (trunk) and as such can be 
hopelessly out of sync with the code.  Even the version of the code that 
somewhat locked down and not under heavy development.  Perhaps we can 
solve this one simply with stronger versioning?

Thanks!
Mark


>
> gustavo @ http://niemeyer.net
>


-- 
Mark Mims, Ph.D.
Canonical Ltd.
mark.mims at canonical.com
+1(512)981-6467