Documentation

On this page we cover details left out of Getting Started. If you want an overview, please see Getting Started. The documentation is a work in progress, feel free to let us know if you can't quickly find what you're looking for.

Table of Contents

• Repository Owners
  • Add a README badge
  • GitHub Issue Summary
• Create Bounties
  • Bounty Types
  • Bounty Creation GitHub Commands
  • Caveat Emptor: A Caution
  • Supported Currencies
  • Expiration
• Earn Bounties
  • Earn Bounty GitHub Commands
  • Supported Countries
  • Data Security
• Command Rules

Repository Owners

A repository owner may send or receive bounties in their own repositories.

Just because a bounty or bounty request is posted on an issue does not mean repo owners must act on it. Repo owners are of course free to "wontfix" issues, or not merge PRs just as if there were no bounties involved. Repo owners are still in total control of the repo and the roadmap of the project, as they should be.

To enable boss commands (e.g. /boss $1000) on your GitHub issues you'll need to install the boss github app. This allows boss to access your issues, PRs, and commits via the GitHub API. You select which organizations and repositories on which to install boss, and you can uninstall the boss app at any time. If you do not want to install boss on some repositories that is no problem: do not select them and boss will not know they exist.

Boss does not change the way in which PRs or commits are merged, that is still entirely controlled by the repository owners. The only change that boss will make is that when boss commands are used in an issue, boss will post a comment to summarize the up-to-date bounty status.

The Boss GitHub app may be installed on private repositories. Private issues will not show up in public lists like open issues with bounties

Add a README Badge

To announce boss is enabled on your repo, put this markdown at the top of your README.md:

[![Boss Bounty Badge](https://img.shields.io/endpoint.svg?url=https://api.boss.dev/badge/enabled/REPO_OWNER/REPO_NAME)](https://www.boss.dev/issues/repo/REPO_OWNER/REPO_NAME)

By default it will appear like this:

You can change the style by changing the query string sent to shields.io, for example to change the style: [![Boss Bounty Badge](https://img.shields.io/endpoint.svg?url=https://api.boss.dev/badge/enabled/REPO_OWNER/REPO_NAME&style=for-the-badge&color=green)](https://www.boss.dev/issues/repo/REPO_OWNER/REPO_NAME)

which will change the style to "for-the-badge" and color to "green" and look like this:

You can find more badge styles at the shields.io endpoint documentation.

GitHub Issue Summary Comment

When boss commands are used or boss bounties are created in a GitHub issue, boss creates a summary comment for the issue. The summary comment aggregates all the bounties, requests, and possible errors in one place. This comment is only created once, and then edited for subsequent updates, to avoid triggering additional github notification emails to peoples' inboxes. If this isn't the behavior you'd prefer, please let us know.

Create Bounties

Bounties are created in either of two ways

1. By creating a bounty via the web UI (login and credit card required). This method does not require that the boss github application has been installed.
2. By entering text commands into github issues. The issue's repository must have the boss github app installed which is typically marked with a README badge:

Anyone with a valid credit card may create bounties. And there are no country restrictions on where bounties come from. If you add credit cards in different currencies, we will always use the card that matches the currency of the bounty you've created, to save you a conversion fee from your credit card company.

The minimum bounty amount is currently $5USD and the maximum is $2000USD (or currency equivalent). In the future, we plan to increase the maximum bounty amount.

Bounty Types

Type	Description
auto	The card is charged automatically after both: the PR/commit closes the issue, and the PR/commit author has enabled receiving bounties. If you do not trust the repo owner use verify type instead.
verify	Does not automatically get charged. After the issue has been closed by a PR or commit, you will need to manually verify the issue has been closed to your satisfaction. Upon satisfaction, you must change the bounty to type thanks, which will then send the money as soon as the bounty earner is ready to receive it.
thanks	Useful when the issue has already been closed by a PR/commit, or when approving a verify bounty after it has been verified. The card is charged immediately after the PR/commit author has enabled receiving bounties.

Create Bounty Commands via GitHub Issues

These commands require that the the boss github app is installed on the github repository.

Command Example, on own line	Description
/boss $1000	Creates an auto type bounty. If you do not trust the repo owner use verify instead.
/boss €1000 verify	Creates a verify type bounty. Upon satisfaction, you must manually edit this issue comment and change it to e.g. /boss €1000 thanks
/boss $1000 thanks	Creates a thanks type bounty. Used when the issue has already been closed by a PR/commit.

You can use these commands at any time, but they will not send a bounty until you've setup a boss account and enabled sending bounties on your account page.

Caveat Emptor: A Caution

Repository owners may close an issue in any fashion they see fit - with any commit/PR or without one. Importantly, they can close an issue with a PR that doesn't actually solve a problem, which would cause attached bounties to be sent anyway. Even if the repository owner is trustworthy, they may have a different understanding than you of what "solving the problem" entails. If you are not confident the repository owner will solve the problem as you expect, use the verify bounty type.

Boss does not issue refunds, though at our sole discretion we may try and help in extreme circumstances.

Supported Currencies

Bounties may be created in any of these 33 currencies:

To create a bounty in one of these currencies use the 3-letter code in your command, e.g.
/boss 2000CAD

You may create a bounty in a foreign currency, but it is typically not recommended since that may cause a conversion fee from your credit card company. But if you happen to know that the bounty recipient receives money in a foreign currency, you could create the bounty in that currency and effectively pay the conversion fee for them.

Bounty Expiration

Bounty expirations will be added in a near future release, at which point we will set a default expiration on all oustanding bounties.

Earn Bounties

You earn a bounty by closing an issue with boss bounties via commit or PR. In the case of a PR, which may contain multiple commits by multiple authors, the bounty earner is the person who created the PR.

When you earn a bounty it will get automatically deposited into your bank account. If the bounty is posted in a foreign currency it will get automatically converted into your native currency before deposit. If you add bank accounts in multiple currencies we will always deposit into the bank account that matches the currency of the bounty, to avoid a conversion fee.

Please note that at the moment only individual persons may receive bounties. Businesses may send bounties, but support for earning bounties will be added in a future release.

Bounty Earner Command Examples

These commands work best if the the boss github app is installed on the github repository.

Command (on own line)	Description
/boss ask $1000	Announce you will close this issue for $1000. In the near future, we will let you know when this number has been reached by one or more bounty creators.
/boss champion	Announce that you are working on the issue. It is still up to the repo owners whether or not to accept and merge your PR. And there may be multiple champions per issue.
/boss onit	alias for champion
/boss volunteer	alias for champion

Supported Countries

To earn bounties you must be a legal resident in at least one of these countries:

• Australia 🇦🇺
• Austria 🇦🇹
• Belgium 🇧🇪
• Canada 🇨🇦
• Denmark 🇩🇰
• Finland 🇫🇮
• France 🇫🇷
• Germany 🇩🇪
• Hong Kong 🇭🇰
• Ireland 🇮🇪
• Italy 🇮🇹
• Japan 🇯🇵
• Luxembourg 🇱🇺
• Netherlands 🇳🇱
• New Zealand 🇳🇿
• Norway 🇳🇴
• Portugal 🇵🇹
• Singapore 🇸🇬
• Spain 🇪🇸
• Sweden 🇸🇪
• Switzerland 🇨🇭
• United Kingdom 🇬🇧
• United States 🇺🇸

If you'd like to earn bounties from a different country please let us know.

Data Security

Your personal and financial information is uploaded safely following best practices. Boss does not store or have access to your sensitive personal information such as government ID numbers or tax id. The information is immediately uploaded to Stripe, a company that specializes in safely handling financial data, and is safely processed by boss using tokens.