Skip to content

Latest commit

 

History

History
276 lines (180 loc) · 7.67 KB

USER_GUIDE.md

File metadata and controls

276 lines (180 loc) · 7.67 KB
Raw

Derek User Guide

This is a user-guide for all the features available in Derek.

Derek can be invoked via comments, or actions on a GitHub repository.

Example of adding a label:

/add label: spam
Derek add label: spam

Get Derek

You can self-host Derek or use the managed service, see GET.md.

Share Derek - with a GitHub badge

Copy the below to your README.md file and replace "owner" and "repo"

[![Derek](https://alexellis.o6s.io/badge?repo=derek&owner=alexellis)](https://github.com/alexellis/derek/)

See alexellis/derek-fn for more.

Enable Derek for a repo

Add a .DEREK.yml file to the repository.

.DEREK.yml schema

Example from this project:

maintainers:
 - rgee0
 - alexellis
 
features:
 - dco_check
 - comments
 - pr_description_required
 - hacktoberfest
 - no_newbies
 - release_notes

This file enables Derek usage for rgee0 and alexellis, it also turns on all features available. If you specifically do not want the commenting or dco_check feature then comment out the line or remove it from your file. At least one feature is required for Derek to be of use.

Feature: release_notes

Derek will collate closed PRs since the last release and then put together a summary and set it for your release text body.

Example from openfaas/faas-cli:

Changelog for 0.9.5:

PR #709 Fix issue with cloud seal command by @viveksyngh
PR #707 Add unit test for secrets in forbidden namespace by @viveksyngh
PR #675 Feature: Add flags for new command to input cpu/memory by @alexellis
PR #681 Propagate the copy error in call stack by @viveksyngh

Generated by Derek

Feature: pr_description_required

If pr_description_required is specified in the feature list then Derek will inform you that a PR needs a description. He also adds the invalid label.

Feature: no_newbies

This feature is designed to deter and intercept spam generated during the Hacktoberfest period.

Any new contributors will have their PRs closed with an empathetic comment and instructions to comment on whether their PR is "not spam". From there, you can remove the "invalid" label and merge the PR if required.

This feature is only advisable during the period of October each year.

Feature: hacktoberfest

This feature is used as an effort to enforce the DigitalOcean Hacktoberfest Quality Standards

If hacktoberfest is specified in the feature list then Derek will check whether all the files included in the pull request are markdown files (ending in .md). If they are, and the user is a first-time contributor, and they did not sign off their commit, Derek will close the Pull Request, and add the invalid label.

Feature: dco_check

If dco_check is specified in the feature list then Derek will inform you when a PR is submitted with commits which have no sign-off message. This is required if your project requires the Developer Certificate of Origin.

Derek will add a label of no-dco and a comment to help the PR submitter fix the commits.

Feature: redirect config

The .DEREK.yml file can be redirected to another repository or site. This is used in the OpenFaaS project where around 12 repos are present with the same permissions, features and users.

Example:

redirect: https://raw.githubusercontent.com/openfaas/faas/master/.DEREK.yml

Feature: comments

If comments is given in the features list then this enables all commenting features as below.

Note: All commands can be given with a prefix of either Derek <command> or /<command>.

Edit title

Let's say a user raised an issue with the title I can't get it to work on my computer

/set title: Question - does this work on Windows 10?

or

/edit title: Question - does this work on Windows 10?

Manage labels

Labels can be used to triage work or help sort it.

/add label: proposal

/add label: help wanted

/remove label: bug

To address multiple labels through a single action use a comma separated list. The maximum number of labels that can be managed in one comment defaults to 5; this can be set to preference through multilabel_limit in your stack.yml

To add multiple labels:

/add label: proposal, help wanted, skill/intermediate

To remove multiple labels:

/remove label: proposal, help wanted

Set a milestone for an issue or PR

You can organize your issues in groups through existing milestones

/set milestone: example

or:

/remove milestone: example

Assign work

You can assign work to people too

/assign: alexellis

Use the me moniker to refer to yourself

/unassign: me

Add a reviewer to a PR

You can assign people for a PR review as well

/set reviewer: alexellis

Use the me moniker to refer to yourself

/clear reviewer: me

Note: Both assigning work and/or PR reviewer rely on the target user being a member of your GitHub organisation or for a personal project, they must be a collaborator with write-access.

Open and close issues and PRs

Sometimes you may want to close or re-open issues or Pull Requests:

/close

/reopen

A reason can also be added if further explanation is appropriate:

/close: not an issue

/reopen: work incomplete

Lock/un-lock conversation/threads

This is useful for when conversations are going off topic or an old thread receives a lot of comments that are better placed in a new issue.

/lock

/unlock

Note: once locked no further comments are allowed apart from users with admin access.

Add predefined message

Have Derek add pre-configured comments to a PR or Issue thread, for example when you would like to direct someone towards the contributing guide.

Configure the feature in .DEREK.yml file. It should look something like:

custom_messages:
  - name: docs
    value: Hello, please check out the docs ...
  - name: slack
    value: |
           -- 
           To join our slack channel ...

Above are two examples which shows simple configuration, the first one is the method for single line messages, the second one is more specific multi line literal, which should be exactly below the | sign in order to be displayed and not having errors while parsing.

Tell derek to send the message:

/message: docs

/msg: slack

Notes on usage

Editing the .DEREK.yml file

The .DEREK.yml file is served by a GitHub CDN which has a 5 minute cache expiry. That means if you make a change, it will take at least 5 minutes before it kicks in.

Multiple-commands in a comment

Multiple commands in a single comment are not yet supported.

Additional white-space

Additional white-space/new-lines in comments are not yet supported

Enroll users to use Derek with your repo

Users can be specified in a list called curators or maintainers - both are offered for when the term maintainer is a loaded term. The Moby project use this variant, for everyone else maintainers may make sense.

Usernames are strictly case-sensitive.

Local overrides and merging config

You can specify a redirect URL in the .DEREK.yml file, this instructs derek to get config from that remote URL. You can also apply local overrides and additions to the config set in the remote file.

For example, to add a contributor to that repo (in addition to the existing contributors) you can specify the remote file and also add the maintainers section to your local file. These lists will then be merged, giving all users in the merged set access to derek.