Best practices

First and foremost, your app must obey the The Three Laws of Robotics:

0. A robot may not harm humanity, or through inaction allow humanity to come to harm.
1. A robot may not injure a human being or, through inaction, allow a human being to come to harm.
2. A robot must obey the orders given to it by human beings except where such orders would conflict with the First Law.
3. A robot must protect its own existence as long as such protection does not conflict with the First or Second Laws.

Now that we agree that nobody will get hurt, here are some tips to make your app more effective.

Contents:

• Empathy
  • Avoid the uncanny valley
• Autonomy
  • Never take bulk actions without explicit permission
  • Include "dry run" functionality
• Configuration
  • Require minimal configuration
  • Provide full configuration
  • Store configuration in the repository

Empathy

Understanding and being aware of the what another person is thinking or feeling is critical to healthy relationships. This is true for interactions with humans as well as apps, and it works both ways. Empathy enhances our ability to receive and process information, and it helps us communicate more effectively.

Think about how people will experience the interactions with your app.

Avoid the uncanny valley

The uncanny valley is the hypothesis that our emotional response to a robot becomes increasingly positive as it appears to be more human, until it becomes eerie and empathy quickly turns to revulsion. This area between a "barely human" and "fully human" is the uncanny valley.

Your app should be empathetic, but it shouldn't pretend to be human. It is an app and everyone that interacts with it knows that.

• 😄 "Latest build failures: {listing of build failures}…"
• 😢 "Hey there! You asked for the build failures, so I went and dug them up for you: {listing of build failures} … Have a fantastic day!"

Autonomy

Never take bulk actions without explicit permission

Being installed on an account is sufficient permission for actions in response to a user action, like replying on a single issue. But an app must have explicit permission before performing bulk actions, like labeling all open issues.

For example, the stale app will only scan a target repository for stale issues and pull requests if .github/stale.yml exists in that target repository.

Include "dry run" functionality

A dry run is when an app, instead of actually taking an action, only logs what actions it would have taken if it wasn't a dry run. An app must offer a dry run feature if it does anything destructive and should offer a dry run feature in all cases.

For example, the stale app will perform a dry run if there is no .github/stale.yml file in the target repository.

Configuration

Require minimal configuration

Apps should provide sensible defaults for all settings.

Provide full configuration

Apps should allow all settings to be customized for each installation.

Store configuration in the repository

Any configuration should be stored in the target repository. Unless the app is using files from an established convention, the configuration should be stored in the .github directory. See the API docs for context.config.

context.config supports sharing configs between repositories. If configuration for your app is not available in the target repository, it will be loaded from the .github directory of the target organization's .github repository.

Users can also choose their own shared location. Use the _extends option in the configuration file to extend settings from another repository.

For example, given .github/test.yml:

_extends: github-settings
# Override values from the extended config or define new values
name: myrepo

This configuration will be merged with the .github/test.yml file from the github-settings repository, which might look like this:

shared1: will be merged
shared2: will also be merged

Just put common configuration keys in a repository within your organization. Then reference this repository from config files with the same name.

You can also reference configurations from other organizations:

_extends: other/probot-settings
other: DDD

Additionally, you can specify a specific path for the configuration by
appending a colon after the project.

_extends: probot-settings:.github/other_test.yaml
other: FFF

Inherited configurations are in the exact same location within the
repositories.

# octocat/repo1:.github/test.yaml
_extends: .github
other: GGG

# octocat/.github:test.yaml
other: HHH

Found a mistake or want to help improve this documentation? Suggest changes on GitHub