From 4a3b90dc5c49883832de1e4927c2f22283f0e877 Mon Sep 17 00:00:00 2001 From: Jason Kuhrt Date: Wed, 22 Apr 2020 14:29:16 -0400 Subject: [PATCH] chore(docs): gh actions recipe + release notes overview --- README.md | 97 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 77 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5d1eff9a..b2f441f8 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,25 @@ Opinionated CLI for continuous delivery of npm packages. + - [Installation](#installation) - [Overview](#overview) - [Pull-Request Releases](#pull-request-releases) - [Canary Releases](#canary-releases) - [Stable Releases](#stable-releases) - [Package.json Version Field](#packagejson-version-field) + - [Release Notes (aka. Changelogs)](#release-notes-aka-changelogs) +- [Recipes](#recipes) + - [Usage inside GitHub Actions](#usage-inside-github-actions) - [CLI](#cli) - - [`dripip get-current-commit-version`](#dripip-get-current-commit-version) - - [`dripip get-current-pr-num`](#dripip-get-current-pr-num) - - [`dripip help [COMMAND]`](#dripip-help-command) - - [`dripip log`](#dripip-log) - - [`dripip pr`](#dripip-pr) - - [`dripip preview`](#dripip-preview) - - [`dripip preview-or-pr`](#dripip-preview-or-pr) - - [`dripip stable`](#dripip-stable) +- [`dripip get-current-commit-version`](#dripip-get-current-commit-version) +- [`dripip get-current-pr-num`](#dripip-get-current-pr-num) +- [`dripip help [COMMAND]`](#dripip-help-command) +- [`dripip log`](#dripip-log) +- [`dripip pr`](#dripip-pr) +- [`dripip preview`](#dripip-preview) +- [`dripip preview-or-pr`](#dripip-preview-or-pr) +- [`dripip stable`](#dripip-stable) @@ -114,18 +118,64 @@ Having a valid semver value in the `version` field is required by npm. Dripip pu 0.0.0-dripip ``` -# CLI +### Release Notes (aka. Changelogs) - +Dripip generates release notes for canary and stable releases. Notes are published within GitHub releases. Canary release notes are published under the `next` tag. Stable release notes are published under its respective version tag. Stable release notes are stable, while Canary release notes are always changing. When a stable release is cut, the canary release notes are cleared since `next` becomes the same as stable, until the next Canary is published. -- [`dripip get-current-commit-version`](#dripip-get-current-commit-version) -- [`dripip get-current-pr-num`](#dripip-get-current-pr-num) -- [`dripip help [COMMAND]`](#dripip-help-command) -- [`dripip log`](#dripip-log) -- [`dripip pr`](#dripip-pr) -- [`dripip preview`](#dripip-preview) -- [`dripip preview-or-pr`](#dripip-preview-or-pr) -- [`dripip stable`](#dripip-stable) +Because the canary release notes have a stable tag, it means you and your uses can _always_ check out what's coming in the next stable version by visiting: + +``` +https://github.com///releases/tag/next +``` + +For example checkout what's coming up in dripip right now by visiting https://github.com/prisma-labs/dripip/releases/tag/next. + +## Recipes + +### Usage inside GitHub Actions + +We are interseted in building a `dripip` GitHub Action. Until it ships, here are the things you need to do. + +1. Have `dripip` installed as a dev dependency +1. Upload an `NPM_TOKEN` to your repo ([gh docs](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)) +1. Expose `GITHUB_TOKEN` to `dripip` ([gh docs](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)) +1. Expose `NPM_TOKEN` to `dripip` +1. Checkout all repo commits and tags + +Example Workflow Configuration: + +```yml +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Get all git commits and tags + run: git fetch --prune --unshallow --tags + - uses: actions/setup-node@v1 + - run: yarn --frozen-lockfile + - run: yarn -s dripip preview-or-pr + env: + NPM_TOKEN: ${{secrets.NPM_TOKEN}} + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} +``` + +Real World Usage: + +- [`dripip`](https://github.com/prisma-labs/dripip/blob/master/.github/workflows/main.yml) +- [`nexus`](https://github.com/graphql-nexus/nexus/blob/master/.github/workflows/trunk.yml) + +## CLI + + +* [`dripip get-current-commit-version`](#dripip-get-current-commit-version) +* [`dripip get-current-pr-num`](#dripip-get-current-pr-num) +* [`dripip help [COMMAND]`](#dripip-help-command) +* [`dripip log`](#dripip-log) +* [`dripip pr`](#dripip-pr) +* [`dripip preview`](#dripip-preview) +* [`dripip preview-or-pr`](#dripip-preview-or-pr) +* [`dripip stable`](#dripip-stable) ## `dripip get-current-commit-version` @@ -137,6 +187,8 @@ OPTIONS -r, --optional Exit 0 if a version for the commit cannot be found ``` +_See code: [dist/cli/commands/get-current-commit-version.ts](https://github.com/prisma-labs/dripip/blob/v0.0.0-dripip/dist/cli/commands/get-current-commit-version.ts)_ + ## `dripip get-current-pr-num` ``` @@ -144,9 +196,11 @@ USAGE $ dripip get-current-pr-num OPTIONS - -r, --optional Exit 0 if a pr number cannot be found for whatever reason (logical, error, ...) + -r, --optional Exit 0 if a pr number cannot be found for whatever reason ``` +_See code: [dist/cli/commands/get-current-pr-num.ts](https://github.com/prisma-labs/dripip/blob/v0.0.0-dripip/dist/cli/commands/get-current-pr-num.ts)_ + ## `dripip help [COMMAND]` display help for dripip @@ -175,6 +229,8 @@ OPTIONS -m, --markdown format output as Markdown ``` +_See code: [dist/cli/commands/log.ts](https://github.com/prisma-labs/dripip/blob/v0.0.0-dripip/dist/cli/commands/log.ts)_ + ## `dripip pr` ``` @@ -209,6 +265,8 @@ USAGE $ dripip preview-or-pr ``` +_See code: [dist/cli/commands/preview-or-pr.ts](https://github.com/prisma-labs/dripip/blob/v0.0.0-dripip/dist/cli/commands/preview-or-pr.ts)_ + ## `dripip stable` ``` @@ -223,5 +281,4 @@ OPTIONS --trunk=trunk State which branch is trunk. Defaults to honuring the "base" branch setting in the GitHub repo settings. ``` -