GitHub workflow

This page shows how organisations and developers interact in a Public Solver Quests workflow.

1️⃣ Org starts a quest

A whitelisted (admin) member of an organisation can initiate a quest by "stashing" a USD reward of reward_value in a GitHub Issue.

To accomplish this, use the Start a Quest button on the admin dashboard and follow on-screen instructions.

Alternatively, for starting public Quests only, call the stash command in the target Issue, specifying the desired reward_value.

@quest-bot stash {reward_value}

Note there is no currency symbol used in the above command. For now, all integer values are taken as USD by default.

If this is successful you will see a message like:

💰 A {reward_value} USD reward has been stashed in this issue! 

...

Click here for common errors with stash.

Note, it is possible to change the value of a reward after a Quest begins using the restash command (see 'Changing Quest reward values' below).

2️⃣ Dev attempts a Quest

After a Quest has started, a developer can express interest in solving it by "embarking" on the Quest. Embarking on a Quest does not provide the developer with exclusivity, but it lets the organisation and other solvers know that they intend to solve it.

To embark on a quest, a developer can use the Quine website, following an explicit invitation link received per Quest.

Alternatively, for embarking on public Quests only, a developer can call the embark command in the target Issue on GitHub.

@quest-bot embark

If this is successful you will see a message like:

@{user} has embarked on this Quest 🗡

...

Now the developer needs to go and submit a Pull Request against the target Issue.

Click here for common errors with embark.

3️⃣ Dev submits a PR

When a developer has created a Pull Request to solve an Issue associated with a Quest, they can link their PR to the relevant Issue (and its stashed reward) via the Quine website, using a GitHub URL to their PR.

Alternatively, for public Quests only, a developer can use the loot command on GitHub.

The loot command can be invoked at any point in the Pull Request lifecycle, but we recommend calling it immediately upon submitting a PR.

The loot command can either be called in the PR body comment when raising the PR (in its first of last line), or in a comment on the PR to follow. The loot command should declare the Issue number that the Pull Request is addressing, referring to the appropriate Issue using it's number in GitHub prepended by a hash symbol, in the form: #{issue_number}. If multiple Quest Issues are being looted under a single PR, they should be separated by a space in the respective comment, and must not include commas or other symbols.

For example, if the developer is looting one Issue (Quest) the formula is:

@quest-bot loot #{issue_number}

If the developer is looting three Issues, the syntax becomes:

@quest-bot loot #{issue_num_1} #{issue_num_2} #{issue_num_3}

Note, it is also possible for a developer to loot a Quest in a different repository than the repo where the relevant PR resides. This can occur if, for example, an Issue is raised in one repo, but the solution relates to code in another repo. To do this, the loot command must include a path reference, with the appropriate issue prepended by its repo name. For example:

@quest-bot loot {repo_name}/#{issue_number}

The above format can also be chained as per other loot commands.

For a successful loot, a message like this will appear on the Pull Request:

@{looter}, you have made a valiant attempt to loot this reward 🤺

...

And a corresponding message with appear on the related Issue(s) itself, notifying all other members that the Quest is being looted.

Click here for common errors with loot.

4️⃣ Org issues reward

When a pull request has been merged, the organisation must explicitly accept loot claims associated with the Issue.

To confirm a reward for the Quest and close the Quest, a whitelisted org admin must either click the corresponding Award solver button that appears in their admin dashboard after a PR is merged

Alternatively, for public Quests only, call the "reward" command in the Issue hosting the Quest (i.e. where the reward has been stashed).

To do this, use the reward command on the Issue where the Quest is being hosted and reference the @username that is to be rewarded.

For example, if the organisation is rewarding the resolution of one Quest, the command is:

@quest-bot reward @{username}

A message like this will appear:

Congratulations @{username}!

You have been victorious in quest (#{issue_number}) 🗡

...

Click here for common errors with reward.

Note, it is also possible to issue rewards via the admin dashboard on the Quine website. To do this, a user must have looted the Quest and a PR must have been merged (as normal). Following this, a 'Award solver' button will appear on the relevant activity stream item relating to the merged PR in the appropriate Quest page. The Quest reward will automatically be issued to the user that raised the PR (and looted), and Quest-bot will post the appropriate reward messages to GitHub to notify all users.

5️⃣ Tipping users

As well as rewarding a developer for a successful solve, an organisation may wish to show its appreciation to others for their contributions to a Quest (for example, for providing partial solutions or other guidance).

In order to support this, we provide a tip functionality.

Tips are freeform (mini) rewards that can be issued to any user at any time during a Quest. All tips are assumed to be a USD amount of tip_value directed to a specific GitHub user using a command in the format:

@quest-bot tip @{username} {tip_value}

Note there is no currency symbol used in the above command. For now, all integer values are taken as USD by default.

💰 Changing Quest reward values

In some scenarios, an organisation may wish to change the value of a reward after a Quest has already started (i.e. after the Quest has originally been 'stashed').

This can be achieved using the restash command in the target Issue, specifying a new reward_value to provide an updated value for the Quest:

@quest-bot restash {reward_value}

Note there is no currency symbol used in the above command. For now, all integer values are taken as USD by default.

If this is successful you will see a message like:

The loot on Quest #{issue_number} has been restashed by @{organisation}.

💰 The loot available is now ${new_reward_value}.

We do not recommend restashing a Quest with a lower reward value than originally specified, since some developers may already have embarked. Instead, an organisation should mainly use restash to increase the value of Quests in cases where not enough developers are embarking, or to attract more experienced developers.

⛔️ Aborting a Quest

In some situations, an organisation might want to abort a Quest. However, this action is not recommended because if a Quest has already started, the work of some developers may go unrewarded.

To abort a Quest, you must call the abort command on the Issue where the Quest was initialised. The Issue number #{issue_number} must be included for added security:

@quest-bot abort #{issue_number}

A confirmation message like this will appear in the Issue. Developers who have called embark on the Quest will be notified:

Swords down 🗡

Quest on issue #{issue_number} has been aborted by @{organisation}

...

Note, Quests can also be aborted directly from the admin dashboard using the 'Manage Quest' menu on the appropriate Quest page.

In the future, we may introduce grace periods for aborting quests. However, at the moment, an organisation is allowed to abort a quest at any point in its lifecycle.

Click here for common errors with abort.

PreviousInstallationNextCommon errors

Last updated