Open Stack

On Thu, Oct 13, 2016 at 01:06:43PM +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.
> 
We do have an abandoned path in gerrit to support this[3], but infra decided to
abandon it since it wasn't very safe. So, it is possible to render markdown in
cgit, we just need to confirm how safe it is today.

[3] https://review.openstack.org/#/c/60375/

> 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



> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev