FUNDING file in repositories

[andrew]

I've seen lots of conventions popping up around having particularly named files in the root directory of repositories as different forms of documentation, things like:

• README
• CODE_OF_CONDUCT
• CONTRIBUTING
• LICENSE
• CHANGELOG
• THREAT_MODEL
• SUPPORT

similarly on the web we have robots.txt and humans.txt

I wonder if there's a place for a FUNDING or SUSTAINABILITY file convention that documents if and how the project is working towards sustainability and outlines how individuals and companies can contribute financially or with in-kind services.

@olivierlacan has done a great job with http://keepachangelog.com in encouraging one of these movements without needing GitHub/GitLab/Bitbucket to add anything to their products to highlight it.

Thoughts?

[jdorfman]

Honestly, I think putting it somewhere in the README file is best since it is the first thing that shows up in the Repo. The only time I read CONTRIBUTING is when GitHub links to it before submitting a PR.

Less is more IMO.

[olivierlacan]

That's very interesting to me. I've been maintaining several production applications with OSS projects for the past five years and it's been a real struggle to find sustainable projects, notice when they stop being sustainable (maintainer quits, issues/PRs balloon up, slow burn out, etc.) or what to switch to (in-house or another OSS project).

I think SUSTAINABILITY is a better idea simply because not all OSS projects are interested in receiving funding.

[RichardLitt]

Good idea! But I don't see why this can't be in the README, as well.

I'm not sure having more all caps files is a great idea. I suspect that it leads to people disconnecting from reading them - I agree that CONTRIBUTING is often the go-to on GitHub only after a PR has been opened (if then!).

[BenJam]

I'm not sure having more all caps files is a great idea.

Amen to that. Might be useful for things where a diff is particularly interesting though. Like a project balance sheet or similar.

[andrew]

I suggested having a separate file as parsing readme files is generally a nightmare, and if a convention appeared around using a particular kind of file we may see things like GitHub add functionality around it, like they've done with license and code of conduct, also we can easily detect it in Libraries.io.

For many projects the GitHub page is the homepage and best place to market things and the file browser appears right at the top of the page, perfect place to catch someone's eye.

[RichardLitt]

parsing readme files is generally a nightmare

Agreed. That's the main motivator behind standard-readme. I think aiming for a conventionalized heading - ## Funding is probably more useful than another file. Can you do a dumb regex for funding and see what that brings up? That term may not bring up many false positives.

Catching someone's eye is a good goal - but if you have five cap files screaming at someone, you're much less likely to catch someone's eye. Too many calls to actions, I think.

[M-Zuber]

Could we maybe encourage a balance of both a mention in the readme with extended discussion in a separate file (similar to what some projects do already with license and contributing files)?

[piamancini]

For those on Open Collective we could include a SUSTAINABILITY file in the PR me make to add backers and sponsors. To test it. But we'd have to define what the idea behind the file is. Something I really like is what cyclejs does: https://github.com/cyclejs/cyclejs/blob/master/CORE_TEAM.md

[andrew]

@piamancini edited that for you!

[piamancini]

@andrew: appreciated. Geez GitHub's mobile interface ...

[jashmenn]

I love this idea. One of the things I've been working through is if we could go so far as having a machine-readable protocol for payment instructions in the package metadata.

For example, in JavaScript, the package.json could have a pay or fund key which specifies the network (bitcoin, paypal) and address (1NwZRGUTw4khTmuV31EUBBQQv37Zrxi9Uu or [email protected]) to which payments could be made.

(In the cryptocurrency space, https://github.com/jashmenn/ihan was one experiment in that direction, but it is pretty limited. We've also been discussing an inter-protocol/network ID over at: uport-project/mnid#4)

Interledger addresses are also interesting because they allow specifying both crypto and "real-world" bank accounts.

In any case, I think we could define a payment protocol for each of the major package managers that defines where payments could go. All package managers allow you to specify the maintainers and their email addresses already, and this data could be described in a similar way.

For example in a package.json you could list:

  "pay": [
    { protocol: "BTC", address: "1B1KNRu6L8n3VFaF9MrU7K87QQALZqL57z", split: 0.8 },
    { protocol: "BTC", address: "1MqqaEHDmfq65gie6RHNsrJZDMZoeB5E6", split: 0.2 }
  ]

(Tbh, the format above isn't great, but hopefully it's enough to get the point across.)

[jashmenn]

A couple of clarifications.

First, by having a machine readable format, the idea is that we can build tools that will automate value transfer / payments. For example, imagine you've built an app and you want to send a donation to all of your dependencies. You could imagine a tool that reads the package.json for your own project, finds all of the (transitive) dependencies that accept payments, and then pays each one a fraction of your donation.

Second, I realize that this idea is narrowly focused on the idea of payments/digital value transfer and not on sustainability at large. There are certainly many other things that go into sustainability of a project and a human-based document like CODE_OF_CONDUCT might be better suited for defining things like in-kind services, etc.

[maxbrito]

Hello,

For example in a package.json you could list

We could likely have both a SUSTAINABILITY file for humans and add the automated info on the json, albeit the number of software projects using something called package.json is very much limited to Javascript and most developers wouldn't likely realize this info is there.

On a slightly unrelated topic: is THREAT_MODEL really used often on other projects?

I've seen SECURITY.MD being used with frequency to guide others on how to report security breaches and/or explain which parts of their product can be more vulnerable (likely the same function as THREAT MODEL) and they are indeed useful.

Examples:
https://github.com/discourse/discourse/blob/master/docs/SECURITY.md
https://github.com/electron/electron/blob/master/SECURITY.md
https://github.com/krakenjs/xcomponent/blob/master/SECURITY.md

[jashmenn]

@maxbrito re: package.json: For sure, package.json is a "JavaScript-mainly" package manager, but my hope is that we could develop a standard that could be used for Go, Rubygems, Pypi, Maven, NuGet, CocoaPods, etc.

I think one of the reasons Interledger addresses are promising is because it packs a lot of information regarding network, fork, and address into a single string. This seems like a good idea because then we wouldn't require the package format to handle more complicated data structures.

@andrew One question I have is if you envision this thread being primarily about FUNDING or SUSTAINABILITY -- I ask because it seems they are related, but separate, things.

[andrew]

@jashmenn mostly just some way for maintainers to convey that they are interested in making the project sustainable in the long term, funding is one aspect of that but they are many other things that factor into sustainability.

[ncoghlan]

From my perspective, I think there would be some key social benefits to encouraging a convention like a "SUSTAINABILITY" file:

• it makes the default state a marker for "I/we haven't really thought about the problem yet"
• for maintenance collectives like Jazzband or the Python Packaging Authority, the SUSTAINABILITY file can indicate that even though something is mainly an individual project, there has been some thought given to continuity planning in the event of something happening to the project founder
• for projects backed by non-profit organisations, governments, or particular corporate sponsors, that can be explicitly acknowledged
• for projects with commercial redistributors, it provides a conventional place to point that out
• for projects with crowdfunding mechanisms in place, language independent machine readable metadata conventions could potentially be defined
• for projects that are actively seeking new contributors, it provides a place to state that and indicate what level of mentoring might be available

As far as the "WHY ARE YOU SHOUTING" concern goes, if the proposed convention allows for both SUSTAINABILITY and a dot-prefixed directory like ".project/SUSTAINABILITY", then projects could choose for themselves how prominent they wanted the file to be.

[ncoghlan]

This PyPI design discussion from last year also seems relevant: https://mail.python.org/pipermail/distutils-sig/2016-July/029297.html

TL;DR of that thread in this context: if SUSTAINABILITY files became a convention, we'd probably work out a way to communicate that info through the PyPI web UI & API

[rachellawson]

In PHP projects, many have the equivalent composer.json and it looks like adding the similar fields would cause no issue. I really like the idea of adding this info directly into the source code. I’m pretty sure Drupal would be happy to do it. I know we are looking in to adding the code of conduct already, once we sort out the licensing (it was adapted from the Ubuntu one, which isn’t GPL compatible) Rachel

…

On 3 Jul 2017, at 21:42, Nate Murray ***@***.***> wrote: @maxbrito re: package.json: For sure, package.json is a "JavaScript-mainly" package manager, but my hope is that we could develop a standard that could be used for Go, Rubygems, Pypi, Maven, NuGet, CocoaPods, etc. I think one of the reasons Interledger addresses are promising is because it packs a lot of information regarding network, fork, and address into a single string. This seems like a good idea because then we wouldn't require the package format to handle more complicated data structures. @andrew One question I have is if you envision this thread being primarily about FUNDING or SUSTAINABILITY -- I ask because it seems they are related, but separate, things. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[jashmenn]

I think that funding instructions are something that could be codified, but there are some details to be worked out, particularly around multi-network addresses.

Since this thread is more for a human-language SUSTAINABILITY document, I've started a new thread here to discuss a format for embedding payment routing information in the package metadata.