[openstack-dev] [all][tc] Exposing project team's metadata in README files

Flavio Percoco flavio at redhat.com
Thu Oct 13 11:06:43 UTC 2016


On 12/10/16 11:01 -0400, Doug Hellmann wrote:
>Excerpts from Flavio Percoco's message of 2016-10-12 14:50:03 +0200:
>> Greetings,
>>
>> One of the common complains about the existing project organization in the big
>> tent is that it's difficult to wrap our heads around the many projects there
>> are, their current state (in/out the big tent), their tags, etc.
>>
>> This information is available on the governance website[0]. Each official
>> project team has a page there containing the information related to the
>> deliverables managed by that team. Unfortunately, I don't think this page is
>> checked often enough and I believe it's not known by everyone.
>>
>> In the hope that we can make this information clearer to people browsing the
>> many repos (most likely on github), I'd like to propose that we include the
>> information of each deliverable in the readme file. This information would be
>> rendered along with the rest of the readme (at least on Github, which might not
>> be our main repo but it's the place most humans go to to check our projects).
>>
>> Rather than duplicating this information, I'd like to find a way to just
>> "include it" in the Readme file. As far as showing the "official" badge goes, I
>> believe it'd be quite simple. We can do it the same way CI tags are exposed when
>> using travis (just include an image). As for the rest of the tags, it might
>> require some extra hacking.
>>
>> So, before I start digging more into this, I wanted to get other opinions/ideas
>> on this topic and how we can make this information more evident to the rest of
>> the community (and people not as familiar with our processes as some of us are).
>>
>> Thanks in advance,
>> Flavio
>>
>> [0] http://governance.openstack.org/reference/projects/index.html
>>
>
>Is your proposal that a tag like release:cycle-with-milestones would
>result in a badge being added when the README.rst is rendered on
>github.com? Would that work for git.openstack.org, too?

I don't think it'd work for git.openstack.org because it doesn't render the
README's[0] like github does. One thing I'd like to avoid is for this
information to result in new changes to the README file everytime the tags are
updated because I'd like for this information to not be duplicated and to make
it clear that this information is not meant to be updated manually.

Here's[1] an example of what it would look like (or kinda).

[0] http://git.openstack.org/cgit/openstack/glance/tree/README.rst
[1] https://github.com/celery/kombu/blob/master/README.rst


>I agree that the governance site is not the best place to put the
>info to make it discoverable. Do users look first at the source
>repository, or at some other documentation?

The feedback* I've gotten is that users normally look at repos first and they go
from there to docs (which are normally linked in the README file).

* Neither based on a survey nor on any empirical research. This is based on
  hallway talks.

Flavio

-- 
@flaper87
Flavio Percoco
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 847 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20161013/bb991d7b/attachment.pgp>


More information about the OpenStack-dev mailing list