Initial work at creating docs

README.md

@@ -163,7 +163,6 @@ Note: this will leave a comment on the PR.
 
 ## Known issues
 
-* We're still figuring out how to handle [async code correctly](https://github.com/danger/danger-js/issues/88) (you can use `await` with no problem though)
 * Codeship support does not support fork to fork GitHub PRs.
 
 ## This thing is broken, I should help improve it!
@@ -200,6 +199,16 @@ Tips:
 
 Check the issues, I try and keep my short term perspective there. Long term is in the [VISION.md](VISION.md).
 
+## License, Contributor's Guidelines and Code of Conduct
+
+We try to keep as much discussion as possible in GitHub issues, but also have a pretty inactive Slack --- if you'd like an invite, ping [@Orta](https://twitter.com/orta/) a DM on Twitter with your email. It's mostly interesting if you want to stay on top of Danger without all the emails from GitHub.
+
+> This project is open source under the MIT license, which means you have full access to the source code and can modify it to fit your own needs.
+
+> This project subscribes to the [Moya Contributors Guidelines](https://github.com/Moya/contributors) which TLDR: means we give out push access easily and often.
+
+> Contributors subscribe to the [Contributor Code of Conduct](http://contributor-covenant.org/version/1/3/0/) based on the [Contributor Covenant](http://contributor-covenant.org) version 1.3.0.
+
 [emiss]: https://github.com/artsy/emission/blob/master/dangerfile.ts
 [danger-js]: https://github.com/danger/danger-js/blob/master/dangerfile.ts
 [meta]: https://github.com/artsy/metaphysics/blob/master/dangerfile.js

dangerfile.ts

@@ -2,7 +2,7 @@
 // This means we can re-use the type infra from the app, without having to
 // fake the import.
 
-import {DangerDSL} from "./source/dsl/DangerDSL"
+import { DangerDSL } from "./source/dsl/DangerDSL"
 declare var danger: DangerDSL
 declare function warn(params: string): void
 declare function fail(params: string): void
@@ -111,8 +111,8 @@ schedule(async () => {
 // Some good old-fashioned maintainance upkeep
 
 // Ensure the danger.d.ts is always up to date inside this repo.
-// This also serves as a way of being able to understand changes to the DSL
-// in a way that doesn't require running Danger.
+// This also serves as the "one true DSL" for a Danger run against a PR
+// which tools can then work against.
 
 import dtsGenerator from "./scripts/danger-dts"
 const currentDTS = dtsGenerator()

docs/getting_started.html.md

@@ -0,0 +1,108 @@
+---
+title: Getting Started with Danger JS
+subtitle: Plugin creation
+layout: guide_js
+order: 0
+---
+
+So, you're ready to get set up. 
+
+There are 5 steps involved in getting Danger running:
+
+* [Include the Danger module](#including-danger).
+* [Creating a Dangerfile](#creating-a-dangerfile) and add a few simple rules.
+* [Creating an account for Danger to use](#creating-a-bot-account-for-danger-to-use).
+* Setting up [an access token for Danger](#setting-up-an-access-token) with that account.
+* Setting up [Danger to run on your CI](#setting-up-danger-to-run-on-your-ci).
+
+### Including Danger
+
+We recommend you install Danger via [Yarn][]. Though you can use the npm CLI.
+
+##### Installation
+
+Adding the Danger module by `yarn run danger --dev`. This will add Danger as a `devDependency` and make the command `danger` available by running `yarn danger`.
+
+### Creating a Dangerfile
+
+Create either an empty JavaScript or TypeScript file named `Dangerfile`. Either `Dangerfile.js` or `Dangerfile.ts` will be picked up automatically.
+
+Danger uses [Jest's][jest] infrastructure for handling source code transpilation for your Dangerfile. This means if you are using Jest for your testing, then you have no configuration. If you do not use Jest, I would recommend looking at their [config settings][jest-config]
+
+To get yourself started, try this as your Dangerfile:
+
+```js
+import { message, danger } from "danger"
+message("OK, this worked @" + danger.github.pr.user.login)
+```
+
+Which, once you have your authentication set up, will have danger post a message to your PR with your name.
+
+For a deeper understanding of using a Dangerfile, see the guide [dangerfiles][]
+
+### Creating a bot account for Danger to use
+
+This is optional. Pragmatically, you want to do this though. Currently Danger JS only supports communication on GitHub. If you're interested in GitLab and BitBucket support, PRs are welcome, or look at the Ruby version of Danger.
+
+### GitHub
+
+In order to get the most out of Danger, we recommend giving her the ability to post comments in your Pull Requests. This is a regular GitHub account, but depending on whether you are working on a private or public project, you will want to give different levels of access to this bot. You are allowed to have [one bot per GitHub account][github_bots].
+
+To get started, open [https://github.com](https://github.com) in a private browser session.
+
+##### OSS Projects
+
+Do not add the bot to your repo or to your organization.
+
+##### Closed Source Projects
+
+Add the bot to your repo or to your organization. The bot requires permission level "Write" to be able to set a PR's status. Note that you _should not_ re-use this bot for OSS projects.
+
+### Setting up an Access Token
+
+[Here's the link][github_token], you should open this in the private session where you just created the new GitHub account. Again, the rights that you give to the token depend on the openness of your projects. You'll want to save this token for later, when you add a `DANGER_GITHUB_API_TOKEN` to your CI.
+
+##### Tokens for OSS Projects
+
+We recommend giving the token the smallest scope possible. This means just `public_repo`, this scopes limits Danger's abilities to just writing comments on OSS projects. Because the token can be quite easily be extracted from the CI environment, this minimizes the chance for bad actors to cause chaos with it.
+
+##### Tokens for Closed Source Projects
+
+We recommend giving access to the whole `repo` scope, and its children.
+
+### Enterprise GitHub
+
+You can work with GitHub Enterprise by setting 2 environment variables:
+
+* `DANGER_GITHUB_HOST` to the host that GitHub is running on.
+* `DANGER_GITHUB_API_BASE_URL` to the host that the GitHub Enterprise API is reachable on.
+
+For example:
+
+```hs
+DANGER_GITHUB_HOST=git.corp.evilcorp.com
+DANGER_GITHUB_API_BASE_URL=https://git.corp.evilcorp.com/api/v3
+```
+
+### Continuous Integration
+
+Continuous Integration is the process of regularly running tests and generating metrics for a project. It is where you can ensure that the code you are submitting for review is passing on all of the tests. You commonly see this as green or red dots next to commits.
+
+Danger is built to run as a part of this process, so you will need to have this set up as a pre-requisite.
+
+### Setting up Danger to run on your CI
+
+(should we do this for DangerJS too?)
+
+/ These docs all come from
+/ https://github.com/danger/danger/tree/master/lib/danger/ci_source
+/ inline documentation, rather than from inside this page.
+
+### Verify Installation
+
+You should be able to verify that you have successfully integrated Danger by either re-building your CI or pushing your new commits.
+
+[jest-config]: SBJDSKDJBSDKJBG
+[github_bots]: https://twitter.com/sebastiangrail/status/750844399563608065
+[github_token]: https://github.com/settings/tokens/new
+[Yarn]: https://yarnpkg.com

docs/the_dangerfile.html.md

@@ -0,0 +1,123 @@
+---
+title: About the Dangerfile
+subtitle: Plugin creation
+layout: guide_js
+order: 1
+---
+
+## Writing your Dangerfile
+
+The Danger JS DSL is fully typed via TypeScript (and eventually Flow again.)  These definitions are shipped with the Danger module. If your text editor supports working with type definitions you will get inline-documentation and auto-completion. Visual Studios Code will do this by default for you.
+
+## Working on your Dangerfile
+
+There are two ways to work and test out your Dangerfile, outside of runnig it on your CI. These both rely on 
+
+#### Using `danger pr`
+
+The command `danger pr` expects an argument of a PR url, e.g. `yarn danger pr https://github.com/danger/danger-js/pull/100`.
+
+This will use your local Dangerfile against the metadata of the linked PR. Danger will then output the results into your terminal, instead of on the PR itself.
+
+#### Using `danger` and Faking being on a CI
+
+If you create an [appropriately scoped temporary api token](http://danger.systems/guides/getting_started.html#setting-up-an-access-token) for your github account, this can be a good way to see if danger is suitable for you before integrating it into your CI system.
+
+You can manually trigger danger against a pull request on the command line by setting the following environmental variables:
+
+```bash
+export DANGER_FAKE_CI="YEP"
+export DANGER_GITHUB_API_TOKEN='xxxxxxxxxx'  # a github api token
+export DANGER_TEST_REPO='username/reponame'
+```
+
+Then you can run against a local branch that is attached to a pull-request, by running the following:
+
+```bash
+git checkout branch-for-pr-1234
+DANGER_TEST_PR='1234' npm run danger
+```
+
+Assuming that your local file-system matches up to that branch on GitHub, this will be a good approximation of how danger will work when you integrate it into your CI system. Note: this will leave a comment on the PR.
+
+## Async
+
+We've not found the perfect pattern for handling different patterns of asynchronous behavior inside a Dangerfile. Here are some patterns for handling them.
+
+* **Ignore Async.** - A Dangerfile is a script, the non-blocking aspect of the node API can be ignored. E.g. use `fs.readFileSync` instead of `fs.readFile`. Danger works really well with [ShellJS][]
+
+* **Scheduling** - The Dangerfile DSL includes a function called `schedule`, this can handle either a promise or a function with a callback arg. For example using `async/await`:
+
+```js
+import { schedule, danger } from "danger"
+
+/// [... a bunch of functions]
+
+schedule(async () => {
+  const packageDiff = await danger.git.JSONDiffForFile("package.json")
+  checkForRelease(packageDiff)
+  checkForNewDependencies(packageDiff)
+  checkForLockfileDiff(packageDiff)
+  checkForTypesInDeps(packageDiff)
+})
+```
+
+In this case, the closure is queued up and Danger waits until all `schedule` functions/promises are finished before continuing, so make sure to not cause it to lock. There is no timeout yet.
+
+## Working with files
+
+Over time, we've found it easier to create up-front arrays of files you are be interested in - then you can work with these potential arrays of files. For example:
+
+```js
+import { danger } from "danger"
+import { includes, concat } from "lodash"
+
+// The Danger DSL can be a bit verbose, so let's rename
+const modified = danger.git.modified_files
+const newFiles = danger.git.created_files
+
+// Have there actually been changes to our app code vs just README changes
+const modifiedAppFiles = modified.filter(p => includes(p, "lib/"))
+const modifiedTestFiles = modified.filter(p => includes(p, "__tests__"))
+
+// Pull out specific files, we want to do against them regardless
+// of whether they are just created or modified.
+const touchedFiles = modified.concat(danger.git.created_files)
+const touchedAppOnlyFiles = touchedFiles.filter(p => includes(p, "src/lib/") && !includes(p, "__tests__"))
+const touchedComponents = touchedFiles.filter(p => includes(p, "src/lib/components") && !includes(p, "__tests__"))
+
+// Now do work against our lists of files
+// ...
+```
+
+## Utils
+
+As the JavaScript library API is relatively limited, the Danger module includes utility functions for work which is common to most Dangerfiles. There can be found in both `utils`, and `github.utils` for GitHub specific functions. We're interested at growing this slowly.
+
+## Nuance
+
+The CHANGELOG for Danger is kept entirely end-user focused, so if there is an aspect of the Dangerfule that you do not know, or looks confusing and there is nothing in the document - check the CHANGELOG. This is where we write-up why a change happened, and how it can affect Danger users.
+
+###Examples
+
+If you'd like to work with some reference material, here are some examples in the wild. 
+
+JavaScript:
+
+* **Apps** - [Artsy/metaphysics][meta].
+* **Libraries** - [Facebook/Jest][fbj], [styled-components/styled-components][sc] and [ReactiveX/rxjs][rxjs].
+
+Some TypeScript examples:
+
+* **Apps** - [Artsy/Emission][emiss]
+* **Libraries** [danger/danger-js][danger-js]
+
+[emiss]: https://github.com/artsy/emission/blob/master/dangerfile.ts
+[danger-js]: https://github.com/danger/danger-js/blob/master/dangerfile.ts
+[meta]: https://github.com/artsy/metaphysics/blob/master/dangerfile.js
+[fbj]: https://github.com/facebook/jest/blob/master/dangerfile.js
+[sc]: https://github.com/styled-components/styled-components/blob/master/dangerfile.js
+[rxjs]: https://github.com/ReactiveX/rxjs/blob/master/dangerfile.js
+[setup]: http://danger.systems/guides/getting_started.html#creating-a-bot-account-for-danger-to-use
+[jest]: https://github.com/facebook/jest
+[ShellJS]: http://github.com/shelljs/shelljs

docs/troubleshooting.html.md

@@ -0,0 +1,36 @@
+---
+title: Troubleshooting
+subtitle: Plugin creation
+layout: guide
+order: 0
+---
+
+
+
+
+### TypeScript without Jest
+
+You'll need to take the following steps for danger to evaluate your `dangerfile.ts`:
+
+* Install the `ts-jest` package - `yarn add ts-jest --dev`
+* Add the following `jest` section to your `package.json`
+
+```json
+{
+  "jest": {
+    "transform": {
+      ".(ts|tsx)": "<rootDir>/node_modules/ts-jest/preprocessor.js"
+    }
+  }
+}
+```
+
+### I want to only run Danger for internal branches
+
+Let's say you run Danger on the same CI service that deploys your code. If that's open source, you don't want to be letting anyone pull out your private env vars. The work around for this is to not simply call Danger on every test run:
+
+``` sh
+'[ ! -z $DANGER_GITHUB_API_TOKEN ] && yarn danger || echo "Skipping Danger for External Contributor"'
+```  
+
+This ensures that Danger only runs when you have the environment variables set up to run.

package.json

@@ -56,7 +56,8 @@
     "build": "shx rm -rf ./distribution && tsc && madge ./distribution --circular",
     "build:watch": "tsc -w",
     "link": "npm run build && chmod +x distribution/commands/danger.js && npm link",
-    "declarations": "ts-node ./scripts/create-danger-dts.ts"
+    "declarations": "ts-node ./scripts/create-danger-dts.ts",
+    "docs": "typedoc -- --json docs/js_ref_dsl_docs.json --includeDeclarations --excludeExternals"
   },
   "repository": {
     "type": "git",
@@ -93,6 +94,7 @@
     "ts-jest": "^19.0.2",
     "ts-node": "^3.0.0",
     "tslint": "^5.0.0",
+    "typedoc": "orta/typedoc#0.5.10-no-types",
     "typescript": "2.2.1"
   },
   "dependencies": {

scripts/danger-docs-ref.ts

@@ -0,0 +1 @@
+/// <reference path="../source/danger.d.ts" />