Open Stack

Sean Dague wrote:
> On 12/17/2013 04:29 PM, Anne Gentle wrote:
>> I want to discuss the needs for publishing governance documents. I think
>> our requirements start as:
>> - need for a place for review and vote tracking on governance documents
>>
>> which this moved some of our documents (reference and resolutions) out
>> of the wiki and into files in an openstack/governance repository.
>>
>> The requirements for reading those documents seems to be changing, as
>> Sean and others are noting that reading these documents on github.com
>> <http://github.com> or git.openstack.org <http://git.openstack.org> is
>> dissatisfying. So https://review.openstack.org/#/c/61380/ is how Sean is
>> addressing the readability concerns I think. 

FWIW the requirements have not been changing, it was always the plan to
publish the governance docs from the repo under a human-readable form
somewhere. We already do this for the "charter" document, which is
(manually) synced from the git repo to the wiki.

I filed, back in September:
https://bugs.launchpad.net/openstack-ci/+bug/1233059

so that we do this automatically.

>> I think that we need to look at the requirements beyond just reading and
>> into these areas, how will we address:
>> - version control (how do I know I'm reading the most recent, can I see
>> the history of changes?)
> You would always be reading the most recent that was approved. As an
> example - http://docs.openstack.org/developer/tempest/ (git hash in
> template for verification).
> 
> Adding a link in the template to the source tree would be a good idea so
> it's easy to know how to contribute.

Yes, I think people interested in the history of our governance
documents can follow the link to the git repo and see the history of the
changes together with which TC members voted on them at the time. It's
actually richer than the "author" information, which would just explain
who the drafter of the proposal was.

> [...]
>> - bug tracking and reporting (offering a feedback loop and ways to track
>> issues and fixes to published content)
> 
> This doesn't affect that in any way from the current state of things.
> Tracking and bug reporting for governance is currently not solved. So
> that's probably another item.

You could also argue that "bugs in governance" have to follow a specific
process due to the formality around the TC, imposed by the Foundation
bylaws and our charter. Basically bugs in the governance are solved by
following the process at the bottom of:
https://wiki.openstack.org/wiki/Governance/TechnicalCommittee . We
already track governance changes requested through MLs and the
governance repo, I don't really want to add launchpad and wiki Talk as
official ways to suggest governance changes.

>> I'm reluctant to have these published to docs.openstack.org
>> <http://docs.openstack.org> rather than wiki.openstack.org
>> <http://wiki.openstack.org> because of needing mechanisms to take care
>> of those requirements listed above. I'm bringing it up here to discuss
>> further --- possibly my concerns can be assuaged but I need a discussion
>> outside of the patch at https://review.openstack.org/#/c/61380/ so I can
>> more clearly illustrate my concerns.
>>
>> To offer two alternative proposals:
>> - create a publish-rst-to-openstack-wiki build
> 
> So, honestly, I'm not a fan of publish to wiki, because wiki's are
> read-write things, and this would be write only mirroring. It breaks the
> assumptions around it.
> 
> Also, I think I've looked at a Talk page on the OpenStack wiki all of 0
> times since my involvement in the project. With all the other tools in
> front of me doing triage of content in the wiki itself is really not
> part of my workflow. Which isn't that it isn't for other people. But
> there are only so many tool switches people can take in a day and still
> be productive. So my proposed fix was gerrit -> sphinx as that's what
> I'm familiar with, and honestly trying to get more and more of the
> Tempest docs that way (and use the wiki less, as we tend to mostly only
> have really stale things there that confuse people coming in from
> google). :)

Publish-to-wiki was my original proposal, but I agree that publishing
read-only copies of governance documents to the wiki sets the wrong
expectations about it: "protected" pages spread the idea that not
everyone should participate in wiki gardening, wiki history does not
contain TC member votes record, and "Talk" feedback which is not the
right way of suggesting governance fixes, so it would likely just get
ignored. Overall I can see this option generate a lot of frustration.

>> - create governance documents that are authored in a format that then
>> look fine in https://github.com/openstack/governance/
>> or http://git.openstack.org/cgit/openstack/governance/
> 
> Mostly, we have the technology to make this stuff pretty and accessible
> to the world, with nice urls today with sphinx. You could put effort
> into cgit to get there, but it doesn't seem like a win, especially when
> the rest of the project documentation goes through this well tested
> pipeline.

Yes, I think publishing to some specific website, together with clear
links to cgit to see history and understand how to propose changes, is
our best bet.

-- 
Thierry Carrez (ttx)

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 901 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-tc/attachments/20131218/29d83666/attachment-0001.pgp>