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

Michael Johnson johnsomor at gmail.com
Wed Nov 30 16:53:08 UTC 2016


Hi Flavio,

These tags don't seem to be rendering/laying out well for octavia:
https://github.com/openstack/octavia/blob/master/README.rst

Any pointers to get this corrected or is this part of the backend
rendering work you mentioned in the keystone message above?

Michael

On Wed, Nov 30, 2016 at 1:34 AM, Flavio Percoco <flavio at redhat.com> wrote:
> On 25/11/16 13:46 +0000, Amrith Kumar wrote:
>>
>> Flavio,
>>
>> I see a number of patches[1] which have been landed on this project but I
>> find
>> that at least the ones that were landed for Trove, and a random sampling
>> of
>> the others all to be different from what you proposed below[2] in one
>> important aspect.
>>
>> In [2] you proposed a structure where the title of the document; or the
>> first,
>> and most prominent heading, would be the existing heading of the document,
>> and
>> the tags would be below that. In [2] for example, that was:
>>
>> "kombu - Messaging library for Python"
>>
>> and the tags would be in smaller font below that.
>
>
> Hi,
>
> Some fixes landed yesterday to improve the badges layout. For those
> interested,
> here's an example of what it looks like now:
>
> https://github.com/openstack/keystone
>
> Basically, the horizontal padding was reduced to the minimum needed and the
> badges width was set to the total width of the image.
>
> Hope this helps,
> Flavio
>
>
>> What I see in [3] the patch for Trove and the proposed example [4] is:
>>
>> "Team and repository tags" as the first, and most conspicuous header, and
>> the
>> header "Trove" below that.
>>
>> In some cases the second header is the same font as the "Team and
>> repository
>> tags" header.
>>
>> I think this change (these 124 changes) as proposed are not consistent
>> with
>> the proposal you made below, and certainly seem to be less suitable than
>> that
>> proposal. The end product for the four trove repositories [4], [5], [6],
>> and
>> [7]
>>
>> I think we should have a discussion on the ML whether we feel that this
>> new
>> structure is the appropriate one, and before some projects approve these
>> changes and others don't that these be all marked WF-1.
>>
>> Thanks,
>>
>> -amrith
>>
>> [1] https://review.openstack.org/#/q/topic:project-badges
>> [2] https://github.com/celery/kombu/blob/master/README.rst
>> [3] https://review.openstack.org/#/c/402547/
>> [4] https://gist.github.com/anonymous/4ccf1cc6e531bb50e78cb4d64dfe1065
>> [5] https://gist.github.com/1f38def1c65c733b7e4cec3d07399e99
>> [6] https://gist.github.com/2f1c6e9b800db6d4a49d46f5b0623c1d
>> [7] https://gist.github.com/9e9e2e2ba4ecfdece7827082114f8258
>>
>>
>>
>>
>>> -----Original Message-----
>>> From: Flavio Percoco [mailto:flavio at redhat.com]
>>> Sent: Thursday, October 13, 2016 7:07 AM
>>> To: OpenStack Development Mailing List (not for usage questions)
>>> <openstack-dev at lists.openstack.org>
>>> Subject: Re: [openstack-dev] [all][tc] Exposing project team's metadata
>>> in
>>> README files
>>>
>>> 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
>
>
>
>
>> __________________________________________________________________________
>> 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
>
>
>
> --
> @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
>



More information about the OpenStack-dev mailing list