Open Stack

On 13/10/16 13:06 +0200, Flavio Percoco wrote:
>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

Just wanted to add one more thing. This badges can be generated automatically
and there's a small project that does this already[0][1]. We can host it or use
it. We do need, however, a small API that will generate the list of "badges".

[0] http://shields.io/
[1] https://img.shields.io/badge/release-cycle--with--milestones-blue.svg

Flavio

>
>>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



-- 
@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/2fdc5ab9/attachment.pgp>