This is a specification for programatically defining how contibutors to open source software prefer to receive donations to their projects. The aim is to be platform agnostic and as flexible as possible, supporting projects ranging from individual developers to large projects where responsibilities may be split.
The simplest spec in a package.json would look like this:
{
"name": "alice-bob-crypto",
"version": "0.0.1",
"description": "The only encrypted messaging suite you'll ever need",
"donate": "https://givethanks.app/u/alice"
}
Donations would be sent to the user "alice" on givethanks.app
If you'd like to split donations between multiple parties, you can define recipient objects:
...
"donate": {
"recipients": [
{
"weight": 70,
"platform": "Thanks",
"address": "https://givethanks.app/u/alice"
},
{
"weight": 30,
"platform": "Thanks",
"address": "https://givethanks.app/u/bob"
}
]
}
Note that if you do not define a weight
, payments are split evenly between all recipients. Any platform
string is valid, but it's up the donation system that uses the spec to handle it. Ideally the donation is split between all platforms, but a donating user is of course free to donate to -either- Alice, Bob, or both. Additionally, not all donation systems may support all payment platforms, for example, givethanks.app doesn't support bitcoin just yet and the donation would go to Alice.
A single user can specify many platforms (only one platform per user is ever selected by the payment system, and priority is given in the order they're listed)
...
"donate": {
"recipients": [
{
"name": "Alice Liddell",
"weight": 70,
"platforms": [
{
"platform": "Thanks",
"address": "https://givethanks.app/u/alice"
},
{
"platform": "Bitcoin",
"address": "3QJmV3qfvL9SuYo34YihAf3sRCW3qSinyC"
}
]
},
{
"name": "Bob Loblaw",
"weight": 30,
"platform": "Bitcoin",
"address": "3QJmV3qfvL9SuYo34YihAf3sRCW3qSinyC"
}
]
}
A project can specify reward tiers as an incentive to donate. The donation system can show these tiers on the project's page, but the rewards should ultimately be fulfilled by the project owners.
...
"donate": {
"platform": "Thanks",
"address": "https://givethanks.app/u/alice",
"reward": {
"currency": "USD",
"tiers": [
{
"threshold": 5,
"name": "Backer",
"frequency": "any",
"description": "If we ever meet in person, your drink is on me!"
},
{
"threshold": 50,
"name": "Gold Sponsor",
"frequency": "monthly",
"description": "Stickers, plus your name (or your company's name) listed in the credits on our README!"
}
]
}
}
This flow type definition documents every possible combination of valid parameters in a donate spec.
type simple = string
type explicit = {
platform: string,
address: string,
name?: string,
email?: string,
weight?: number,
reward?: reward
}
type explicitMultiPlatform = {
platforms: Array<{
platform: string,
address: string
}>,
name?: string,
email?: string,
weight?: number,
reward?: reward
}
type multiRecipient = {
recipients: Array<simple|explicit|explicitMultiPlatform>
}
type reward = {
currency?: string,
tiers?: Array<rewardTiers>
}
type rewardTier = {
threshold: number,
name: string,
frequency: 'any'|'monthly',
description": string
}
export type donateSpecType = simple|explicit|multiRecipient|explicitMultiPlatform
If your software is published on NPM, once you've added the donate
field to your package.json, you'll need to publish your lastest version. Almost immediately, your donate info should be live at https://givethanks.app/donate/npm/PACKAGE_NAME
Once your package.json
or .donate.json
is pushed up to GitHub, you can see your updated project immediately at https://givethanks.app/donate/github/AUTHOR/REPO
-
If you have a
package.json
, the"donate"
field will always be used. -
If you do not have a
package.json
or it doesn't have a"donate"
field, you can add a.donate.json
file. -
If your package is published on NPM, the spec found there takes precedence over the one found in the project's GitHub, so don't forget to publish a new version if you update your donate spec.
Weights can be defined arbitrarily, and do not have to total any specific amount. For example, a 70 / 30 split is just as valid as 16 / 9. The parser is ultimately responsible for calculating weights as a fraction of the total weight of all recipients.
While all platform strings are valid, this is a list of commonly used ones for ease of parsing.
Platform Name | String |
---|---|
GiveThanks.app | 'Thanks' |
Bitcoin | 'Bitcoin' |
PayPal | 'PayPal' |
Patreon | 'Patreon' |
Open Collective | 'OpenCollective' |
Liberapay | 'Liberapay' |
Buy me a coffee | 'BuyMeACoffee' |
If you have ideas on how to improve this spec, please feel free to submit a pull request!