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

Steve Martinelli s.martinelli at gmail.com
Wed Nov 30 20:16:01 UTC 2016


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

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/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.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.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/4e1cfceb/attachment.html>


More information about the OpenStack-dev mailing list