From a94ad5f04ee4c39eb003fce4ca561ba5a7a3ef98 Mon Sep 17 00:00:00 2001 From: Orta Therox Date: Sat, 15 Apr 2017 11:33:50 -0400 Subject: [PATCH] More docs --- docs/guides/getting_started.html.md | 2 +- docs/guides/the_dangerfile.html.md | 13 +++++- docs/guides/troubleshooting.html.md | 1 - docs/tutorials/node-app.html.md | 1 + docs/tutorials/node-library.html.md | 62 ++++++++++++++++++++++++----- 5 files changed, 65 insertions(+), 14 deletions(-) diff --git a/docs/guides/getting_started.html.md b/docs/guides/getting_started.html.md index d6ecdad88..1d49d1020 100644 --- a/docs/guides/getting_started.html.md +++ b/docs/guides/getting_started.html.md @@ -79,7 +79,7 @@ You can work with GitHub Enterprise by setting 2 environment variables: For example: -```hs +```sh DANGER_GITHUB_HOST=git.corp.evilcorp.com DANGER_GITHUB_API_BASE_URL=https://git.corp.evilcorp.com/api/v3 ``` diff --git a/docs/guides/the_dangerfile.html.md b/docs/guides/the_dangerfile.html.md index c1db91aa2..9cdd151af 100644 --- a/docs/guides/the_dangerfile.html.md +++ b/docs/guides/the_dangerfile.html.md @@ -9,9 +9,19 @@ order: 1 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. +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 runnig it on your CI. These both rely on +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. + +```sh +export DANGER_GITHUB_API_TOKEN='xxxxxxxxxx' +``` + +Then the danger CLI will use these authenticated api calls. #### Using `danger pr` @@ -121,3 +131,4 @@ Some TypeScript examples: [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 diff --git a/docs/guides/troubleshooting.html.md b/docs/guides/troubleshooting.html.md index ce3e9533a..927371df9 100644 --- a/docs/guides/troubleshooting.html.md +++ b/docs/guides/troubleshooting.html.md @@ -5,7 +5,6 @@ layout: guide order: 0 --- - ### I only want to run Danger for internal contributors 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: diff --git a/docs/tutorials/node-app.html.md b/docs/tutorials/node-app.html.md index 160b056f9..df1cc31f8 100644 --- a/docs/tutorials/node-app.html.md +++ b/docs/tutorials/node-app.html.md @@ -81,6 +81,7 @@ More mature tools may have a JSON output reporter, so you can parse that file an + [started]: /js/guides/asdasdasdas [Artsy]: http://artsy.github.io [no-slacking]: https://github.com/alloy/no-slacking-on-pull-requests-bot diff --git a/docs/tutorials/node-library.html.md b/docs/tutorials/node-library.html.md index 6778d9d75..96bbe9591 100644 --- a/docs/tutorials/node-library.html.md +++ b/docs/tutorials/node-library.html.md @@ -11,23 +11,63 @@ This guide continues after "[Getting Started][started]" - so you should have see ## Keeping on top of your library -* CHANGELOG (checking for lib changes) -* Dependencies -* Release PRs -* Interacting with your source, eg. +End-users want to understand what has changed between versions of your library, and a CHANGELOG is a great way to keep them up to date. However, it can be easy to forget to add a CHANGELOG entry to any changes to a library. So let's add a check that a CHANGELOG entry is added on every PR: + +```js +import { danger, fail, warn } from "danger" +import includes from "lodash.includes" + +const hasCHANGELOGChanges = includes(danger.git.modified_files, "CHANGELOG.md") +if (!hasCHANGELOGChanges) { + warn("This pull request may need a CHANGELOG entry.") +} +``` + +We're using lodash's `_.include` function to check if `CHANGELOG.md` is in the list of modified files. + +We went with `warn` here because there are a lot of legitimate reasons to not need a CHANGELOG entry (updating typoes, CI and other infrastructure.) We can improve this though, let's _also_ check that there are changes to the source code for our library. + +```js +import { danger, fail, warn } from "danger" +import includes from "lodash.includes" +import first from "lodash.first" + +const hasCHANGELOGChanges = includes(danger.git.modified_files, "CHANGELOG.md") +const hasLibraryChanges = first(danger.git.modified_files, path => path.startsWith("lib/")) +if (hasLibraryChanges && !hasCHANGELOGChanges) { + warn("This pull request may need a CHANGELOG entry.") +} +``` + +This is a much more specific rule, now changes to the README won't warrant a CHANGELOG entry. + +### Dependencies + +Any dependencies that you use are passed on to all of your library consumers, so you should consider using Danger to keep track of those as they evolve. For more information, see the tutorial on [Dependencies][deps]. + +### Keep your README up to date + +An example from Danger itself, is that we want to ensure the README always shows what CI providers will work by default with Danger. As both the app, and Danger use JavaScript, we can import code from the app and use that to create a new rule. ``` js -// Always ensure we name all CI providers in the README. These -// regularly get forgotten on a PR adding a new one. +import { danger, fail, warn } from "danger" +import contains from "lodash.contains" +// This is a list of all the CI providers import { realProviders } from "./source/ci_source/providers" -import Fake from "./source/ci_source/providers/Fake" -const readme = fs.readFileSync("README.md").toString() -const names = realProviders.map(p => new p({}).name) -const missing = names.filter(n => !readme.includes(n)) + +const readme = fs.readFileSync("README.md", "utf8") +const names = realProviders.map(ci => new ci({}).name) +const missing = names.filter(name => !contains(readme, name)) if (missing.length) { warn(`These providers are missing from the README: ${sentence(missing)}`) } ``` -and our `danger.d.ts` checks +Danger also uses a similar check to create our type definition files, if any of the public DSL changes then Danger checks that the type definitions have been updated, and recommends how to do so if not. + +### + +* Release PRs + +[deps]: AasASDASDASDA