From 338bc88bb1f6858d6bfe7534bf6cb3b525350db1 Mon Sep 17 00:00:00 2001 From: Orta Therox Date: Mon, 26 Jun 2017 08:15:16 -0400 Subject: [PATCH 1/4] README tweaks --- README.md | 201 ++++++++++-------------------------------------------- 1 file changed, 37 insertions(+), 164 deletions(-) diff --git a/README.md b/README.md index fb23aaf74..6c311027b 100644 --- a/README.md +++ b/README.md @@ -1,169 +1,48 @@ -[![npm](https://img.shields.io/npm/v/danger.svg)](https://www.npmjs.com/package/danger) -[![Build Status](https://travis-ci.org/danger/danger-js.svg?branch=master)](https://travis-ci.org/danger/danger-js) -[![Build Status](https://ci.appveyor.com/api/projects/status/ep5hgeox3lbc5c7f?svg=true)](https://ci.appveyor.com/project/orta/danger-js/branch/master) +# Danger JS :no_entry_sign: [![npm](https://img.shields.io/npm/v/danger.svg)](https://www.npmjs.com/package/danger) [![Build Status](https://travis-ci.org/danger/danger-js.svg?branch=master)](https://travis-ci.org/danger/danger-js) [![Build Status](https://ci.appveyor.com/api/projects/status/ep5hgeox3lbc5c7f?svg=true)](https://ci.appveyor.com/project/orta/danger-js/branch/master) -Danger on Node, wonder what's going on? see [VISION.md](VISION.md) +Formalize your Pull Request etiquette. -_Welcome!_ +

+ What is Danger JS? • + Vision • + Helping Out • + Plugin Development +

-So, what's the deal? Well, right now Danger JS does a lot of the simpler parts of [the Ruby version](http://danger.systems). -You can look at [Git](https://github.com/danger/danger-js/blob/master/source/dsl/GitDSL.ts) metadata, or [GitHub](https://github.com/danger/danger-js/blob/master/source/dsl/GitHubDSL.ts) metadata on Travis CI, Circle CI, Semaphore, Jenkins, Docker Cloud, surf-build, Codeship, Drone, Buildkite, or buddybuild. +## What is Danger JS? -Danger can fail your build, write a comment on GitHub, edit it as your PR changes and then delete it once you've passed review. Perfect. +Danger runs after your CI, automating your team's conventions surrounding code review. -## Getting set up in your Project +This provides another logical step in your process, through this Danger can help lint your rote tasks in daily code review. -```sh -# with yarn -yarn add danger --dev - -# or with npm -npm install --save-dev danger -``` - -If using NPM, add a run command to your `package.json` - -```json -{ - "scripts": { - "danger": "danger" - } -} -``` - -Then create a `dangerfile.js` in the project root with some rules: - -```js -import { danger, fail, warn } from "danger" -import fs from "fs" - -// Make sure there are changelog entries -const hasChangelog = danger.git.modified_files.includes("changelog.md") -if (!hasChangelog) { fail("No Changelog changes!") } - -const jsFiles = danger.git.created_files.filter(path => path.endsWith("js")) - -// new js files should have `@flow` at the top -const unFlowedFiles = jsFiles.filter(filepath => { - const content = fs.readFileSync(filepath) - return !content.includes("@flow") -}) - -if (unFlowedFiles.length > 0) { - warn(`These new JS files do not have Flow enabled: ${unFlowedFiles.join(", ")}`) -} -``` - -You can also write your Dangerfile in TypeScript. Create `dangerfile.ts` in the project root with some rules: - -```ts -import { danger, warn } from "danger" -import * as _ from "lodash" - -// Request a CHANGELOG entry if not declared #trivial -const hasChangelog = _.includes(danger.git.modified_files, "changelog.md") -const isTrivial = _.includes((danger.github.pr.body + danger.github.pr.title), "#trivial") -if (!hasChangelog && !isTrivial) { - warn("Please add a changelog entry for your changes.") - - // Politely ask for their name on the entry too - const changelogDiff = danger.git.diffForFile("changelog.md") - const contributorName = danger.github.pr.user.login - if (changelogDiff && _.includes(changelogDiff, contributorName)) { - warn("Please add your GitHub name to the changelog entry, so we can attribute you correctly.") - } -} -``` - -Using [Jest][jest] and TypeScript for testing? You're all set - Danger should be able to use your `jest` config in `package.json` to process and evaluate your `dangerfile.ts`. - -Not using Jest on your TypeScript project? 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)": "/node_modules/ts-jest/preprocessor.js" - } - } -} -``` - -Then you add `yarn run danger` to the end of your CI run, and Danger will run. Here's [an example](https://github.com/artsy/emission/pull/385). 👍 - -Want to see some existing JavaScript examples? Check out: +You can use Danger to codify your teams norms, leaving humans to think about harder problems. -- **Apps** - [Artsy/metaphysics][meta]. -- **Libraries** - [Facebook/Jest][fbj], [styled-components/styled-components][sc] and [ReactiveX/rxjs][rxjs]. +Danger JS currently works with GitHub and Travis CI, Circle CI, Semaphore, Jenkins, Docker Cloud, surf-build, Codeship, Drone, Buildkite, or buddybuild. -Some TypeScript examples: +## For example? -- **Apps** - [Artsy/Emission][emiss] -- **Libraries** [danger/danger-js][danger-js] +You can: -I'd love PRs adding more. +- Enforce CHANGELOGs +- Enforce links to Trello/JIRA in PR/MR bodies +- Enforce using descriptive labels +- Look out for common anti-patterns +- Highlight interesting build artifacts +- Give warnings when specific files change -## Getting set up on CI +Danger provides the glue to let _you_ build out the rules specific to your team's culture, offering useful metadata and a comprehensive plugin system to share common issues. -For now, to get set up I'd recommend looking at [the setup guide for the Ruby version][setup]. All the environment vars are the exact same between versions. +## Getting Started -You will need to create a bot account, and set up CI to run danger. +Alright. So, actually, you may be in the wrong place. From here on in, this README is going to be for people who are interested in working on and improving on Danger JS. -If you are using Docker Cloud, make sure to set the following blank ENV vars in your `docker-compose.test.yml` file so they are carried forward from the build environment: +We keep all of the end-user documentation at . -```yml -sut: - build: . - environment: - - DANGER_GITHUB_API_TOKEN - - DOCKER_REPO - - PULL_REQUEST_URL - - SOURCE_REPOSITORY_URL -``` - -## Running/Testing manually against a repo - -There are two ways to do this: - -#### Using `danger pr` - -The command `danger pr` expects an argument of a PR url, e.g. `danger pr https://github.com/danger/danger-js/pull/100`. - -This will use your local `dangerfile.js` against the metadata of that PR. Danger will then output the results as JSON, instead of on the PR itself. - -#### Using `danger` - -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' -``` +Some quick links to get you started: -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. - -## Advice - -- You can have Danger read build logs if you use [tee](https://en.wikipedia.org/wiki/Tee_(command)) in your CI process: `yarn run lint | tee linter_output.txt`. This can then be picked up with `readFileSync` at `linter_output.txt` in your Dangerfile later. - -## Known issues - -- Codeship support does not support fork to fork GitHub PRs. +- [Getting Started](http://danger.systems/js/guides/getting_started.html) +- [Guides Index](http://danger.systems/js/guides.html) +- [DSL Reference](http://danger.systems/js/reference.html) ## This thing is broken, I should help improve it! @@ -186,14 +65,8 @@ yarn test yarn lint ``` -* * * - -### Dev Life - -Tips: - -- You can run the `danger` command globally from your dev build by running `yarn run link`. -- If you're using VS Code, press Run to start an example run, should go through most of the process with a debugger attached. Either use breakpoints, or add `debugger` to get a repl and context. +The fixers for both tslint and prettier will be applied when you commit, and on a push your code will be verified +that it compiles. ### What is the TODO? @@ -203,12 +76,12 @@ Check the issues, I try and keep my short term perspective there. Long term is i Following [this commit](https://github.com/danger/danger-js/commit/a26ac3b3bd4f002acd37f6a363c8e74c9d5039ab) as a model: -* Checkout the `master` branch. Ensure your working tree is clean, and make sure you have the latest changes by running `git pull`. -* Update `package.json` with the new version - for the sake of this example, the new version is **0.21.0**. -* Modify `changelog.md`, adding a new `### 0.21.0` heading under the `### Master` heading at the top of the file. -* Commit both changes with the commit message **Version bump**. -* Tag this commit - `git tag 0.21.0`. -* Push the commit and tag to master - `git push origin master --follow-tags`. Travis CI will build the tagged commit and publish that tagged version to NPM. +- Checkout the `master` branch. Ensure your working tree is clean, and make sure you have the latest changes by running `git pull`. +- Update `package.json` with the new version - for the sake of this example, the new version is **0.21.0**. +- Modify `changelog.md`, adding a new `### 0.21.0` heading under the `### Master` heading at the top of the file. +- Commit both changes with the commit message **Version bump**. +- Tag this commit - `git tag 0.21.0`. +- Push the commit and tag to master - `git push origin master --follow-tags`. Travis CI will build the tagged commit and publish that tagged version to NPM. :ship: From 45c727cda90c2854a2dec4a87a87a55b4b2f66f0 Mon Sep 17 00:00:00 2001 From: Orta Therox Date: Tue, 27 Jun 2017 07:13:00 -0400 Subject: [PATCH 2/4] Creates inline docs for all providers --- changelog.md | 2 ++ source/ci_source/providers/BuddyBuild.ts | 14 ++++++++++++ source/ci_source/providers/Buildkite.ts | 18 +++++++++++++++ source/ci_source/providers/Codeship.ts | 25 ++++++++++++++++++++- source/ci_source/providers/DockerCloud.ts | 27 ++++++++++++++++++++++- source/ci_source/providers/Jenkins.ts | 5 +++-- 6 files changed, 87 insertions(+), 4 deletions(-) diff --git a/changelog.md b/changelog.md index 96f771465..407699f68 100644 --- a/changelog.md +++ b/changelog.md @@ -2,6 +2,8 @@ ### Master +- Adds inline docs for all CI providers - orta + ### 0.21.1 - Use HTTP for the GitHub status check target URL - macklinu diff --git a/source/ci_source/providers/BuddyBuild.ts b/source/ci_source/providers/BuddyBuild.ts index 2ff154478..1cc672c9e 100644 --- a/source/ci_source/providers/BuddyBuild.ts +++ b/source/ci_source/providers/BuddyBuild.ts @@ -1,6 +1,20 @@ import { Env, CISource } from "../ci_source" import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers" +/** + * ### CI Setup + * + * Buddybuild has an integration for Danger JS already built-in. + * + * ### Token Setup + * + * Login to buddybuild and select your app. Go to your *App Settings* and + * in the *Build Settings* menu on the left, choose *Environment Variables*. + * + * #### GitHub + * Add the `DANGER_GITHUB_API_TOKEN` to your build user's ENV. + * + */ export class BuddyBuild implements CISource { constructor(private readonly env: Env) {} diff --git a/source/ci_source/providers/Buildkite.ts b/source/ci_source/providers/Buildkite.ts index ffe4cce58..101cff405 100644 --- a/source/ci_source/providers/Buildkite.ts +++ b/source/ci_source/providers/Buildkite.ts @@ -1,6 +1,24 @@ import { Env, CISource } from "../ci_source" import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers" +/** + * ### CI Setup + * + * With BuildKite you run the server yourself, so you will want to run it as a part of your build process. + * It is common to have build steps, so we would recommend adding this to your scrip: + * + * ``` shell + * echo "--- Running Danger" + * bundle exec danger + * ``` + * + * ### Token Setup + * + * #### GitHub + * + * 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" bundle exec danger`. + */ export class Buildkite implements CISource { constructor(private readonly env: Env) {} diff --git a/source/ci_source/providers/Codeship.ts b/source/ci_source/providers/Codeship.ts index c056938ac..4b9fad1d3 100644 --- a/source/ci_source/providers/Codeship.ts +++ b/source/ci_source/providers/Codeship.ts @@ -2,8 +2,31 @@ import { Env, CISource } from "../ci_source" import { ensureEnvKeysExist, getPullRequestIDForBranch } from "../ci_source_helpers" /** - * Docs: TODO + * ### CI Setup + * + * To make Danger run, add a new steo to the `codeship-steps.yml` file: + * + * ``` + * - type: parallel: + * ... + * - name: danger + * service: web + * command: yarn danger + * ``` + * + * ### Token Setup + * + * You'll want to edit your `codeship-services.yml` file to include a reference + * to the Danger authentication token: `DANGER_GITHUB_API_TOKEN`. + * + * ``` + * project_name: + * ... + * environment: + * - DANGER_GITHUB_API_TOKEN=[my_token] + * ``` */ + export class Codeship implements CISource { private default = { prID: "0" } constructor(private readonly env: Env) {} diff --git a/source/ci_source/providers/DockerCloud.ts b/source/ci_source/providers/DockerCloud.ts index cc4a0a51d..b2ef3a7b6 100644 --- a/source/ci_source/providers/DockerCloud.ts +++ b/source/ci_source/providers/DockerCloud.ts @@ -2,8 +2,33 @@ import { Env, CISource } from "../ci_source" import { ensureEnvKeysExist } from "../ci_source_helpers" /** - * Docs: TODO + * + * ### CI Setup + * + * You'll want to add danger to your existing `Dockerfile.test` (or whatever you + * have choosen as your `sut` Dockerfile.) + * + * ```sh + * ... + * + * CMD ["yarn", "danger"] + * ``` + * + * ### Token Setup + * + * #### GitHub + * + * Your `DANGER_GITHUB_API_TOKEN` will need to be exposed to the `sut` part of your + * `docker-compose.yml`. This looks similar to: + * + * ``` + * sut: + * ... + * environment: + * - DANGER_GITHUB_API_TOKEN=[my_token] + * ``` */ + export class DockerCloud implements CISource { constructor(private readonly env: Env) {} diff --git a/source/ci_source/providers/Jenkins.ts b/source/ci_source/providers/Jenkins.ts index 26a79beeb..8e42ad89b 100644 --- a/source/ci_source/providers/Jenkins.ts +++ b/source/ci_source/providers/Jenkins.ts @@ -1,8 +1,9 @@ import { Env, CISource } from "../ci_source" import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers" + +// https://jenkins-ci.org + /** - * https://jenkins-ci.org - * * ### CI Setup * Ah Jenkins, so many memories. So, if you're using Jenkins, you're hosting your own environment. * From 423df1334d43797f141a61220829d6e46ef7d52b Mon Sep 17 00:00:00 2001 From: Macklin Underdown Date: Tue, 27 Jun 2017 11:29:42 -0400 Subject: [PATCH 3/4] Clean up Jenkins doc formatting and URLs --- source/ci_source/providers/Jenkins.ts | 28 +++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/source/ci_source/providers/Jenkins.ts b/source/ci_source/providers/Jenkins.ts index 8e42ad89b..1748baa89 100644 --- a/source/ci_source/providers/Jenkins.ts +++ b/source/ci_source/providers/Jenkins.ts @@ -1,29 +1,29 @@ import { Env, CISource } from "../ci_source" import { ensureEnvKeysExist, ensureEnvKeysAreInt } from "../ci_source_helpers" -// https://jenkins-ci.org +// https://jenkins.io/ /** - * ### CI Setup - * Ah Jenkins, so many memories. So, if you're using Jenkins, you're hosting your own environment. + * ### 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. + * ### GitHub + * You will want to be using the + * [GitHub pull request builder plugin](https://wiki.jenkins.io/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. + * With that set up, you can edit your job to add `yarn danger` at the build action. * - * ### Pipeline + * ### 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. + * [GitHub branch source plugin](https://wiki.jenkins.io/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. + * 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 + * ## Token Setup * - * ### GitHub - * As you own the machine, it's up to you to add the environment variable for the `DANGER_GITHUB_API_TOKEN`. + * ### 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) {} From 43b68981a3321f3f50caa4d4edccc27f030fbb10 Mon Sep 17 00:00:00 2001 From: David Buchan-Swanson Date: Wed, 28 Jun 2017 07:41:28 +1000 Subject: [PATCH 4/4] Add information about codeship classic for docs --- source/ci_source/providers/Codeship.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/source/ci_source/providers/Codeship.ts b/source/ci_source/providers/Codeship.ts index 4b9fad1d3..5d69a3de3 100644 --- a/source/ci_source/providers/Codeship.ts +++ b/source/ci_source/providers/Codeship.ts @@ -4,7 +4,7 @@ import { ensureEnvKeysExist, getPullRequestIDForBranch } from "../ci_source_help /** * ### CI Setup * - * To make Danger run, add a new steo to the `codeship-steps.yml` file: + * To make Danger run, add a new step to the `codeship-steps.yml` file: * * ``` * - type: parallel: @@ -14,6 +14,8 @@ import { ensureEnvKeysExist, getPullRequestIDForBranch } from "../ci_source_help * command: yarn danger * ``` * + * If you're using Codeship Classic, add `yarn danger` to your 'Test Commands' + * * ### Token Setup * * You'll want to edit your `codeship-services.yml` file to include a reference @@ -25,6 +27,9 @@ import { ensureEnvKeysExist, getPullRequestIDForBranch } from "../ci_source_help * environment: * - DANGER_GITHUB_API_TOKEN=[my_token] * ``` + * + * If you're using Codeship Classic, add `DANGER_GITHUB_API_TOKEN` to your + * 'Environment' settings. */ export class Codeship implements CISource {