Port over Danger RB's inline docs for a CI

docs/guides/faq.html.md

@@ -5,11 +5,9 @@ layout: guide
 order: 0
 ---
 
-This ensures that Danger only runs when you have the environment variables set up to run.
-
 ### Can Danger comment inside a file on an PR?
 
-Not yet, but there is a lot of discussion on [danger-js#77][77]
+Not yet, but there is a lot of discussion on [danger-js#77][77].
 
 ### I want to help influence Danger's direction
 

docs/usage/extending-danger.html.md

@@ -5,3 +5,4 @@ layout: guide_js
 order: 0
 ---
 
+Plugin infrastructure similar to how 

source/ci_source/providers/Circle.ts

@@ -1,6 +1,34 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers"
 
+/**
+ *  ### CI Setup
+ *
+ *  For setting up Circle CI, we recommend turning on "Only Build pull requests." in "Advanced Setting." Without this enabled,
+ *  it is _really_ tricky for Danger to know whether you are in a pull request or not, as the environment metadata
+ *  isn't reliable.
+ *
+ *  With that set up, you can you add `yarn danger` to your `circle.yml`. If you override the default
+ *  `test:` section, then add it as an extra step. Otherwise add a new `pre` section to the test:
+ *
+ *    ``` ruby
+ *    test:
+ *      override:
+ *          - yarn danger
+ *    ```
+ *
+ *  ### Token Setup
+ *
+ *  There is no difference here for OSS vs Closed, add your `DANGER_GITHUB_API_TOKEN` to the Environment variable settings page.
+ *
+ *  ### I still want to run commit builds
+ *
+ *  OK, alright. So, if you add a `DANGER_CIRCLE_CI_API_TOKEN` then Danger will use the Circle API to look up
+ *  the status of whether a commit is inside a PR or not. You can generate a token from inside the project set_trace_func
+ *  then go to Permissions > "API Permissions" and generate a token with access to Status. Take that token and add
+ *  it to Build Settings > "Environment Variables".
+ *
+ */
 export class Circle implements CISource {
   constructor(private readonly env: Env) {
   }

source/ci_source/providers/Codeship.ts

@@ -1,6 +1,9 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist, getPullRequestIDForBranch } from "../ci_source_helpers"
 
+/**
+ * Docs: TODO
+ */
 export class Codeship implements CISource {
   private default = { prID: "0" }
   constructor(private readonly env: Env) {

source/ci_source/providers/DockerCloud.ts

@@ -1,6 +1,9 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist } from "../ci_source_helpers"
 
+/**
+ * Docs: TODO
+ */
 export class DockerCloud implements CISource {
   constructor(private readonly env: Env) {
   }

source/ci_source/providers/Drone.ts

@@ -1,6 +1,27 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers"
 
+/**
+ *
+ *  ### CI Setup
+ *
+ *  With Drone, you run the docker images yourself, so you will want to add `yarn danger` at the end of
+ *  your `.drone.yml`.
+ *
+ *   ``` shell
+ *    build:
+ *      image: golang
+ *        commands:
+ *          - ...
+ *          - yarn danger
+ *   ```
+ *
+ *  ### Token Setup
+ *
+ *  As this is self-hosted, you will need to add the `DANGER_GITHUB_API_TOKEN` to your build user's ENV. The alternative
+ *  is to pass in the token as a prefix to the command `DANGER_GITHUB_API_TOKEN="123" yarn danger`.
+ */
+
 export class Drone implements CISource {
   constructor(private readonly env: Env) {
   }

source/ci_source/providers/Jenkins.ts

@@ -1,6 +1,29 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers"
-
+/**
+ *  https://jenkins-ci.org
+ *
+ *  ### CI Setup
+ *  Ah Jenkins, so many memories. So, if you're using Jenkins, you're hosting your own  environment.
+ *
+ *  #### GitHub
+ *  You will want to be using the
+ *  [GitHub pull request builder plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin)
+ *  in order to ensure that you have the build environment set up for PR integration.
+ *
+ *  With that set up, you can edit your job to add `yarn danger` at the build action.
+ *
+ *  ##### Pipeline
+ * If you're using [pipelines](https://jenkins.io/solutions/pipeline/) you should be using the
+ * [GitHub branch source plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitHub+Branch+Source+Plugin) for easy setup and handling of PRs.
+ *
+ *  After you've set up the plugin, add a `sh 'yarn danger'` line in your pipeline  script and make sure that build PRs is enabled.
+ *
+ *  ### Token Setup
+ *
+ *  #### GitHub
+ *  As you own the machine, it's up to you to add the environment variable for the  `DANGER_GITHUB_API_TOKEN`.
+ */
 export class Jenkins implements CISource {
   constructor(private readonly env: Env) {
   }

source/ci_source/providers/Semaphore.ts

@@ -1,6 +1,18 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers"
 
+/**
+ *  ### CI Setup
+ *
+ *  For Semaphor you will want to go to the settings page of the project. Inside "Build Settings"
+ *  you should add `yarn danger` to the Setup thread. Note that Semaphore only provides
+ *  the build environment variables necessary for Danger on PRs across forks.
+ *
+ *  ### Token Setup
+ *
+ *  You can add your `DANGER_GITHUB_API_TOKEN` inside the "Environment Variables" section in the settings.
+ *
+ */
 export class Semaphore implements CISource {
   constructor(private readonly env: Env) {
   }

source/ci_source/providers/Surf.ts

@@ -1,6 +1,17 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers"
 
+/**
+ *  ### CI Setup
+ *
+ *  You want to add `yarn danger` to your `build.sh` file to run  Danger at the
+ *  end of your build.
+ *
+ *  ### Token Setup
+ *
+ *  As this is self-hosted, you will need to add the `DANGER_GITHUB_API_TOKEN` to your build user's ENV. The alternative
+ *  is to pass in the token as a prefix to the command `DANGER_GITHUB_API_TOKEN="123" yarn danger`.
+ */
 export class Surf implements CISource {
   constructor(private readonly env: Env) {
   }

source/ci_source/providers/Travis.ts

@@ -1,6 +1,27 @@
 import { Env, CISource } from "../ci_source"
 import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers"
-
+/**
+ * ### CI Setup
+ *  You need to edit your `.travis.yml` to include `yarn danger`. If you already have
+ *  a `script:` section then we recommend adding this command at the end of the script step: `- yarn danger`.
+ *
+ *   Otherwise, add a `before_script` step to the root of the `.travis.yml` with `yarn danger`
+ *
+ *   ```ruby
+ *     before_script:
+ *       - yarn danger
+ *   ```
+ *
+ *  Adding this to your `.travis.yml` allows Danger to fail your build, both on the TravisCI website and within your Pull Request.
+ *  With that set up, you can edit your job to add `yarn danger` at the build action.
+ *
+ *  ### Token Setup
+ *
+ *  You need to add the `DANGER_GITHUB_API_TOKEN` environment variable, to do this,
+ *  go to your repo's settings, which should look like: `https://travis-ci.org/[user]/[repo]/settings`.
+ *
+ *  If you have an open source project, you should ensure "Display value in build log" enabled, so that PRs from forks work.
+ */
 export class Travis implements CISource {
   constructor(private readonly env: Env) {
   }