Merge pull request #288 from danger/docs-2

Updates to a bunch of docs as a part of work on danger.systems/js

changelog.md

@@ -16,6 +16,8 @@
 This is my first non-trivial plugin, based on infrastructure from @macklinu.
 Plugins are looking great, you can get some info at <https://github.com/macklinu/generator-danger-plugin>.
 
+-   Docs updates for the website - orta
+
 ### 0.20.0
 
 -   Fix `danger pr` commands are not running on windows - kwonoj

docs/guides/culture.html.md

@@ -9,7 +9,7 @@ order: 2
 
 It can be easy to try and jump straight from no Dangerfile to a 200 line complex set of cultural rules. We'd advise against introducing a long list of rules for Danger all at once. In our experience, gradual integration works better. The entire team may have agreed on the changes, but slower adoption has worked better for teams new to working with Danger.
 
-At Artsy we've found that first just integrating Danger with a single simple rule (like checking for a CHANGELOG entry) then starting to introduce them piece-meal from different contributors has made it easier to go from "Ah, we shouldn't do that again" to "Oh, we could make a Danger rule for that" to "Here's the PR". 
+At Artsy we've found that first just integrating Danger with a single simple rule (like checking for a CHANGELOG entry) then starting to introduce complexity piece-meal. Encouraging different contributors to make the changes has made it easier to go from "Ah, we shouldn't do that again" to "Oh, we could make a Danger rule for that" to "Here's the PR".
 
 That is your end goal, making it so that everyone feels like it's easy to add and amend the rules as a project evolves. Making dramatic changes erodes that feeling, making regular small ones improves it.
 
@@ -19,10 +19,10 @@ One of Danger's greatest features is that it can free individuals up on the team
 
 You should use Danger to provide impartial feedback. Consider how these messages come across:
 
-* You have not added a CHANGELOG entry.
-* There isn't a CHANGELOG entry.
-* No CHANGELOG entry.
-* This PR does not include a CHANGELOG entry.
+-   You have not added a CHANGELOG entry.
+-   There isn't a CHANGELOG entry.
+-   No CHANGELOG entry.
+-   This PR does not include a CHANGELOG entry.
 
 The first feels like a statement that someone has intentionally done something wrong, and Danger has caught them in the act.
 
@@ -31,3 +31,16 @@ The second aims to feel a like like a testing framework telling you "Test Suites
 The third if done consistently can work out well. Terse entries can work well when you have a large series of rules, as it feels like a check list to do.
 
 The fourth is what we generally try to aim for, an impartial but polite mention about the state of submitted PR.
+
+You can find what fits for you and your team, but being blameless in your messaging is one way to ensure that someone's first and 500th interaction is still great.
+
+## Positive Rules
+
+Danger doesn't have to be used to provide a checklist of TODOs which have to be done. You can make rules that celebrate achievements, for example:
+
+-   Submit congratulations when your app has had a version bump.
+-   Thank the author for reducing the dependency tree.
+-   Highlighting when someone has removed more code than adding it.
+-   If there are notably tricky areas of the codebase, pass along a thumbs up for daring to improve it.
+
+There's aren't contrived either - I've seen variations on all of these rules inside Dangerfiles. 

docs/guides/faq.html.md

@@ -9,23 +9,30 @@ order: 3
 
 Not yet, but there is a lot of discussion on [danger-js#77][77].
 
+## My
+
 ## Can I use the same Dangerfile across many repos?
 
-Ish, it's currently quite complex to set up, but work is on-going on [Danger/Peril][peril]. This is a hosted version of Danger which does not need to run on CI. Using Peril you can use Dangerfiles to reply to basically any github webhook type.
+Ish, it's currently quite complex to set up, but work is on-going on [Danger/Peril][peril]. This is a hosted version of Danger which does not need to run on CI. Using Peril you can use Dangerfiles to reply to basically any GitHub webhook type.
 
 ## I want to help influence Danger's direction
 
 We'd recommend first becoming acquainted with the [VISION.md][] inside Danger, this is the long-term plan. Then there are two ways to start contributing today:
 
- * Opinions are extra welcome on issues marked as [Open For Discussion][open].
- 
- * Well defined work items like features or fixes are marked as [You Can Do This][you-can-do-this].
+-   Opinions are extra welcome on issues marked as [Open For Discussion][open].
+
+-   Well defined work items like features or fixes are marked as [You Can Do This][you-can-do-this].
 
 We keep comments in the public domain, there is a Slack, but it's very rarely used. If you're interested in joining, you can DM [orta][].
 
 [77]: https://github.com/danger/danger-js/issues/77
-[VISION.md]: https://github.com/danger/danger-js/blob/master/VISION.md
+
+[vision.md]: https://github.com/danger/danger-js/blob/master/VISION.md
+
 [open]: https://github.com/danger/danger-js/issues?q=is%3Aissue+is%3Aopen+label%3A%22Open+for+Discussion%22
+
 [you-can-do-this]: https://github.com/danger/danger-js/issues?q=is%3Aissue+is%3Aopen+label%3A%22You+Can+Do+This%22
+
 [orta]: https://twitter.com/orta/
-[peril]:  https://github.com/danger/peril
+
+[peril]: https://github.com/danger/peril

docs/guides/getting_started.html.md

@@ -9,11 +9,11 @@ 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).
+-   [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
 
@@ -48,7 +48,7 @@ This is optional. Pragmatically, you want to do this though. Currently Danger JS
 
 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.
+To get started, open <https://github.com> in a private browser session.
 
 ### OSS Projects
 
@@ -74,8 +74,8 @@ We recommend giving access to the whole `repo` scope, and its children.
 
 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.
+-   `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:
 
@@ -95,7 +95,7 @@ Danger is built to run as a part of this process, so you will need to have this
 (should we do this for DangerJS too?)
 
 / These docs all come from
-/ https://github.com/danger/danger/tree/master/lib/danger/ci_source
+/ <https://github.com/danger/danger/tree/master/lib/danger/ci_source>
 / inline documentation, rather than from inside this page.
 
 ### Verify Installation
@@ -106,21 +106,30 @@ You should be able to verify that you have successfully integrated Danger by eit
 
 There are a few of places you can go from here. We'd recommending opening tabs on all these articles:
 
-* [The Dangerfile][dangerfile].
-* [Cultural Changes of Danger][culture].
-* [The Dangerfile API reference][api].
+-   [The Dangerfile][dangerfile].
+-   [Cultural Changes of Danger][culture].
+-   [The Dangerfile API reference][api].
 
 Then depending on the type of project you are working on, checking out either [Danger + Node App][app], or [Danger + Node Library][lib]. These should give you good overview of what is possible from here, then it's really up to you to find how you can codify some aspects of your team's culture.
 
 Good luck!
 
 [jest]: https://facebook.github.io/jest/
+
 [jest-config]: https://facebook.github.io/jest/docs/configuration.html
+
 [github_bots]: https://twitter.com/sebastiangrail/status/750844399563608065
+
 [github_token]: https://github.com/settings/tokens/new
-[Yarn]: https://yarnpkg.com
+
+[yarn]: https://yarnpkg.com
+
 [api]: /js/reference.html
+
 [dangerfile]: /js/guides/the_dangerfile.html
-[culture]: /js/guides/culture.html
+
+[culture]: /js/usage/culture.html
+
 [app]: /js/tutorials/node-app.html
+
 [lib]: /js/tutorials/node-library.html

docs/guides/the_dangerfile.html.md

@@ -7,29 +7,27 @@ 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.
+The Danger JS DSL is fully typed via TypeScript. 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 after you import danger in your Dangerfile. Visual Studios Code will do this by default for you.
 
 If you are using Babel in your project, your Dangerfile will use the same transpilation settings. If you're using TypeScript + Jest it will work out of the box too, however, if you don't, you should head over to the [TypeScript guide][ts_guide]
 
 ## Working on your Dangerfile
 
-There are two ways to work and test out your Dangerfile, outside of running it on your CI and checking the results. 
-
-These both rely on using the GitHub API locally, so you may hit the GitHub API rate-limit or need to have authenticated request for private repos. In which case you can use an access token to do authenticated requests by exposing a token to Danger.
+There are two ways to locally work on your Dangerfile.  These both rely on using the GitHub API locally, so you may hit the GitHub API rate-limit or need to have authenticated request for private repos. In which case you can use an access token to do authenticated requests by exposing a token to Danger.
 
 ```sh
 export DANGER_GITHUB_API_TOKEN='xxxxxxxxxx'
 ```
 
 Then the danger CLI will use these authenticated API calls.
 
-#### Using `danger pr`
+### 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.
+This will use your local Dangerfile against the metadata of the linked PR. Danger will then output the results into your terminal, instead of inside the PR itself.
 
-#### Using `danger` and Faking being on a CI
+### 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.
 
@@ -54,9 +52,9 @@ Assuming that your local file-system matches up to that branch on GitHub, this w
 
 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][]
+-   **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`:
+-   **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"
@@ -102,33 +100,42 @@ const touchedComponents = touchedFiles.filter(p => includes(p, "src/lib/componen
 
 ## 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.
+As the JavaScript library API is relatively limited, the Danger module includes utility functions for work which is common to most Dangerfiles. These functions can be found in both `utils`, and `github.utils` for GitHub specific functions. We're interested at growing this carefully.
 
-## Nuance
+## Finding more info
 
-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.
+The CHANGELOG for Danger is kept entirely end-user focused, so if there is an aspect of the Dangerfile that you do not know, or looks confusing and there is nothing in the documentation - 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].
+-   **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]
+-   **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
-[ts_guide]: DFSDGSDFDgdsgdfgd
+
+[shelljs]: http://github.com/shelljs/shelljs
+
+[ts_guide]: /js/tutorials/typescript.html

docs/guides/troubleshooting.html.md

@@ -9,26 +9,28 @@ order: 4
 
 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
+```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. This is how Danger works for a lot of the mobile projects work in Artsy.
+This ensures that Danger only runs when you have the environment variables set up to run. This is how Danger works for a lot of the open source mobile projects in Artsy.
 
 ## I'm seeing a lot of Cannot read property 'bind' in my tests
 
 This causes all of your tests to fail.
 
-```
-  ● Test suite failed to run
+      ● Test suite failed to run
 
-    TypeError: Cannot read property 'bind' of undefined
+        TypeError: Cannot read property 'bind' of undefined
 
-      at Runtime._createRuntimeFor (node_modules/jest-cli/node_modules/jest-runtime/build/index.js:709:52)
-      at handle (node_modules/worker-farm/lib/child/index.js:41:8)
-      at process.<anonymous> (node_modules/worker-farm/lib/child/index.js:47:3)
-      at emitTwo (events.js:106:13)
-      at process.emit (events.js:191:7)
-```
+          at Runtime._createRuntimeFor (node_modules/jest-cli/node_modules/jest-runtime/build/index.js:709:52)
+          at handle (node_modules/worker-farm/lib/child/index.js:41:8)
+          at process.<anonymous> (node_modules/worker-farm/lib/child/index.js:47:3)
+          at emitTwo (events.js:106:13)
+          at process.emit (events.js:191:7)
 
 This seems to happen when you have multiple versions of Jest inside the same project. Danger aims to keep up to date with the latest Jest versions. So you may need to update one or the other. There's [more information here](https://github.com/facebook/jest/issues/3114).
+
+#### Danger is not posting to GitHub PRs, but everything looks fine?
+
+Try logging in to the GitHub account that should be writing the messages, it's possible that your account has triggered the bot detection algorithm on GitHub. This means that messages are sent correctly, but do not show up for anyone except the sender. This makes it more or less impossible to detect from Danger's side.

docs/tutorials/node-app.html.md

@@ -52,8 +52,8 @@ if (danger.github.pr.body.length < 10) {
 
 This can be expanded to all sorts of checks for example:
 
-* Making sure every PR references an issue, or JIRA ticket.
-* Skipping particular rules based on what someone says inside the message. E.g. "This is a trivial PR."
+-   Making sure every PR references an issue, or JIRA ticket.
+-   Skipping particular rules based on what someone says inside the message. E.g. "This is a trivial PR."
 
 ## Results of CI Processes
 
@@ -70,34 +70,38 @@ If your tool does not have an extra log file output option, you can look at usin
 
 And here's a really simple check that it contains the word "Failed" and to post the logs into the PR.
 
-```js
-import { danger, markdown } from "danger"
+````js
+            import { danger, markdown } from "danger"
 
-import contains from "lodash-contains"
-import fs from "fs"
+            import contains from "lodash-contains"
+            import fs from "fs"
 
-const testFile = "tests-output.log"
-const linterOutput = fs.readFileSync(testFile).toString()
+            const testFile = "tests-output.log"
+            const linterOutput = fs.readFileSync(testFile).toString()
 
-if (contains(linterOutput, "Failed")) {
-  const code = "```"
-  markdown(`These changes failed to pass the linter:
+            if (contains(linterOutput, "Failed")) {
+              const code = "```"
+              markdown(`These changes failed to pass the linter:
 
-${code}
-${linterOutput}
-${code}
-  `)
-}
-```
+            ${code}
+            ${linterOutput}
+            ${code}
+              `)
+            }
+````
 
-More mature tools may have a JSON output reporter, so you can parse that file and create your own markdown table.
+More mature tools may have a JSON output reporter, so you can parse that file and create your own report for danger to post.
 
 If you build something that is a generic wrapper around a specific linting tool, this is a great place to convert that code [into a plugin][plugin] so that anyone can use it. In this case, Danger effectively is a way of moving these messages into the code review session.
 
-
 [started]: /js/guides/getting_started.html
-[Artsy]: http://artsy.github.io
+
+[artsy]: http://artsy.github.io
+
 [no-slacking]: https://github.com/alloy/no-slacking-on-pull-requests-bot
+
 [pr]: https://developer.github.com/v3/pulls/#get-a-single-pull-request
+
 [tee]: http://linux.101hacks.com/unix/tee-command-examples/
+
 [plugin]: /js/usage/extending-danger.html