Contributor icons in README files

[Julian-O]

At the bottom of some (not all) of the README.md files in Kivy projects is an acknowledgement to the people who have been involved. This appears fairly straightforward, but has more intricacies than one might think.

[I was about to write some of this in review comments on a PR in PyJnius, and I thought it would be better if future maintainers could find it more easily, so I am posting here instead.]

OpenCollective Terminology

OpenCollective provide three ways you can donate money to Kivy: A one-off donation, become a $US5+/month backer or a $US100+/month sponsor.

(We tell sponsors they will get a logo and link to their site in the README.)

OpenCollective variously call the group of all sponsors/backers/donors "contributors" or "financial contributors".

OpenCollective's glossary talks about "code contributors" too.

OpenCollective Banners

OpenCollective provide banners - in the form of URLs to auto-generated SVGs that contain tables of icons for each person. Each icon is a clickable link.

By default, as the list of people grows, the size of each icon shrinks, but this can be overridden in the URL.

One banner displays all sponsors.

One banner displays all backers.

One banner displays all "contributors", and the documentation is terribly vague.

One might expect that these are all the financial contributors (i.e. sponsors+backers+donors)? But, no - the sponsors' logos are missing and I am on the list, and to date I have not been financial.

Are these code contributors to a subrepo (i.e. pyjnius in the pyjnius README)? No, because the URL doesn't include the specific repo.

Are these code contributors to any Kivy subrepo, or just the kivy/kivy subrepo specifically? I suspect the latter, because only the Kivy/Kivy README includes these links. I assume the person with admin access to Open Collective can tell us.

I have not seen a way to display the one-off donors.

By default, a donate button is added as the last avatar icon. This can be turned off with a setting in the URL.

OpenCollective also offer URLs to return the nth sponsor's avatar image and URL. - i.e. we can show the 8th sponsor (sorted by time? by money donated? Haven't investigated.)

Banners versus GitHub Markdown

Each of these SVG banner's icons are theoretically clickable, but we embed them with an img tag, which eliminates any interactivity. (This is generally a good idea for untrusted SVGs.)

By default, GitHub will add a link to the SVG file itself, so effectively a page of nothing but icons. These icons are indeed clickable.

Generally, we add overriding link tags to the image, which makes clicking on the rendered image jump off to a different point, and the individual icons links are now unreachable.

But we promised the sponsors a clickable logo.

The solution originally used to address this problem was to not use an SVG, but to hardcode OpenCollective links for the 1st sponsor's avatar, the 2nd sponsor's avatar, up to the 10th sponsor's avatar. - i.e. OpenCollective continue to maintain the database of sponsors, and we say "Insert the 1st sponsor's avatar here".

The problem with this solution is it has a hardcoded limit of 10 to the number of sponsors displayed - and we currently have 16 sponsors. A newer version in Master for Kivy extends that to 30, which should buy us a few years, but the resulting MarkDown code is unpleasant.

There is no way to turn off the "Become a Sponsor" button - it appears as the last avatar.

[A few of the sponsors are now defunct and the URLs lead to errors, which is another part of the unpleasantness.]

One possible alternative is to remove the overriding link, so clicking an avatar will take the user to a page of clickable avatars, and adding some text to the readme suggesting they click twice to learn about a sponsor.

Another possible alternative is embedding the SVG more directly in the MarkDown; not sure if MarkDown will support this.

Banners versus GitHub Caches

GitHub attempts to cache the SVG files and host them on their own servers. If the SVG is too large (bytes? pixels? Not sure) it returns a
"Content too long" or similar error. Putting all the contributors avatars at 45 pixels high each is too large.

My Plan

• Make the README.md files consistent.
• Include the OpenCollective contributor link only on Kivy/Kivy.
• Include a GitHub contributor count badge at the top. Have it link to GitHub's contributor list for that repo.
• Mention backers much like now - icons, large enough to make out the images, with no donate button. Let the link go through to the SVG.
• List the first 30-40 sponsors, using the ugly, ugly "nth sponsor" code through gritted teeth, wishing there was another way we could agree to.

[misl6]

Great explanation of the current status, and yeah, thank you for moving the discussion here.

About the plan:

• Making the README.md files consistent and cleaner sounds good, and meanwhile, if we can improve things, why not?

• Some ideas:

  • Code Contributors:
    • Use https://github.com/Xhofe/gh-contributors to handle code contributors of the specific repo (we can host our own if we do not trust the https://contrib.nn.ci/api?repo=[user/repo] endpoint.
    • Add a call to action that links to CONTRIBUTING.md
  • OpenCollective backers and sponsors:
    • I agree about mentioning backers much like now, as you said.
    • Add a link to "see all our backers", like we're doing on the website.
    • List the first 16 sponsors (4 rows, 4 cols), by using the ugly code (we list only our top sponsors)
    • Add a link to "see all our sponsors", like we're doing on the website.
    • Add a call to action, similar to the one available on the website:
      

[Julian-O]

I tried implementing @misl6's suggestions above, and with more investigation, I got to more complexity.

• The gh-contributors looks great, once you figure out you must provide the "pages" parameter or it only shows a limited number.

• "we list only our top sponsors" I cannot find any documentation for the URLs in the "ugly code" (e.g. https://opencollective.com/kivy/sponsor/0/avatar.svg), but based on observation, it appears to be our top current sponsors. So, for example, Bluedynamics KG, who have historically been the second most generous sponsor, but haven't contributed this month, don't make an appearance. Just making that clear, so there are no surprises.

• "(4 rows, 4 cols)" Only on large displays. The SVG comes with some annoying padding, and I would rather just use word-wrapping than a MarkDown table to handle smaller screen sizes.