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

Armando M. armamig at gmail.com
Wed Nov 30 23:04:31 UTC 2016


On 30 November 2016 at 12:16, Steve Martinelli <s.martinelli at gmail.com>
wrote:

> This happened to us for keystone-specs [1]. I settled on removing the
> reference to the README.rst from the doc folder. You can do the same by
> removing [2].
>
> [1] https://review.openstack.org/#/c/402878/
> [2] https://github.com/openstack/neutron-lib/blob/
> master/doc/source/readme.rst
>

Thanks Steve, we'll follow suit!

Cheers,
Armando


>
> On Wed, Nov 30, 2016 at 2:44 PM, Armando M. <armamig at gmail.com> wrote:
>
>>
>>
>> On 30 November 2016 at 08:53, Michael Johnson <johnsomor at gmail.com>
>> wrote:
>>
>>> 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?
>>>
>>>
>> Actually I just noticed that this may break building docs locally for
>> some envs as I now get in my env:
>>
>> Warning, treated as error:
>> README.rst:None: WARNING: nonlocal image URI found:
>> http://governance.openstack.org/badges/neutron-lib.svg
>>
>> I was aware of [1], and I am unsure on the next steps. Can some advise?
>>
>> Thanks,
>> Armando
>>
>> [1] https://review.openstack.org/#/c/229951/
>>
>>
>>> 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/4ccf1cc6e531bb50e78cb4d64d
>>> fe1065
>>> >> [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.op
>>> enstack.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.op
>>> enstack.org?subject:unsubscribe
>>> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>> >
>>>
>>> ____________________________________________________________
>>> ______________
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe: OpenStack-dev-request at lists.op
>>> enstack.org?subject:unsubscribe
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>>
>>
>> ____________________________________________________________
>> ______________
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscrib
>> e
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
>
> __________________________________________________________________________
> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20161130/84a1db8e/attachment.html>


More information about the OpenStack-dev mailing list