Minor release 0.6.3 (#17)

- gh-pr: Document -script-file flag
- gh-pr: readme: Add an example
- readme: Document required OAuth scopes (fixes #16)

README.md

@@ -1,6 +1,8 @@
 # gh-tools
 
-GitHub Tools
+![gh-find image](https://user-images.githubusercontent.com/779965/105617575-09331480-5dad-11eb-82cb-bde13473aa4f.png)
+
+GitHub productivity tools
 
 - [gh-purge-artifacts](cmd/gh-purge-artifacts) Purge GitHub Actions artifacts across GitHub repositories
 - [gh-go-rdeps](cmd/gh-go-rdeps) Find reverse Go dependencies across GitHub repositories
@@ -9,9 +11,9 @@ GitHub Tools
 
 ## Authentication
 
-All tools require a GitHub access token in order to authenticate API requests and use following methods, in the order of precedence, to infer/set the token:
+All tools require a GitHub personal access token in order to authenticate API requests and use following methods, in the order of precedence, to infer/set the token:
 
-- If `-token` flag is used a user will be asked to enter the token interactively
+- `-token` flag, in which case the user will be asked to enter the token interactively
 - `GHTOOLS_TOKEN` environment variable
 - `GITHUB_TOKEN` environment variable
 - `~/.config/gh-tools/auth.yml` file, containing the token
@@ -20,4 +22,14 @@ All tools require a GitHub access token in order to authenticate API requests an
     oauth_token: <token>
     ```
 
-- `gh cli`'s configuration file
+- GitHub's official CLI tool [`gh`](https://github.com/cli/cli) configuration file, to avoid creating separate personal accesss tokens
+
+Here's how you can [create a personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
+
+Your personal access token may need the following scopes to use `gh-tools`:
+
+- `repo`
+- `workflow`
+- `read:user`
+
+The explicit `worklow` scope is requred if you want to be able to make changes to GitHub Actions workflow files with `gh-pr` tool.

cmd/gh-pr/README.md

@@ -27,6 +27,7 @@ Flags:
   -repo=            The pattern to match repository names
   -review=          The GitHub user login to request the PR review from
   -script=          The script to apply changes
+  -script-file=     Read the script from a file
   -shell=           The shell to use to run the script. Default bash
   -title=           The PR title
   -token            Prompt for an Access Token
@@ -37,6 +38,39 @@ Flags:
 
 `GHTOOLS_TOKEN` and `GITHUB_TOKEN` in the order of precedence can be used to set a GitHub access token.
 
-### Examples
+### Example
 
-TBD.
+Walk over all repositories with names starting with `api-` in the GitHub organization `org` and for each repository upgrade `aws-sdk-go` to `v1.35.0`, create a respective pull request, assign it to `john` and request PR reviews from `chris` and `linda`
+
+```sh
+gh-pr -branch upgrade-aws-sdk-to-1-35 \
+-assign john -review chris -review linda \
+-title 'Update aws-sdk-go to v1.35.0' \
+-desc 'Ref: issue#123' \
+-script-file "$HOME/src/scripts/upgrade-aws-sdk.sh" \
+-repo '^api-' org
+```
+
+where `$HOME/src/scripts/upgrade-aws-sdk.sh` may look like this
+
+```sh
+#!/usr/bin/env bash
+
+if [ ! -f go.mod ]; then
+    echo "There is no go.mod"
+    exit
+fi
+
+version=$(go list -m -f '{{ .Version }}' github.com/aws/aws-sdk-go)
+if [ -z "$version" ]; then
+    echo "No aws-sdk-go dependency"
+    exit
+fi
+if [ "$version" == "v1.35.0" ]; then
+    echo "Already using aws-sdk-go v1.35.0"
+    exit
+fi
+
+go mod edit -require='github.com/aws/[email protected]'
+go mod tidy
+```

cmd/gh-pr/main.go

@@ -41,6 +41,7 @@ Flags:
   -repo=            The pattern to match repository names
   -review=          The GitHub user login to request the PR review from
   -script=          The script to apply changes
+  -script-file=     Read the script from a file
   -shell=           The shell to use to run the script
   -title=           The PR title
   -token            Prompt for an Access Token

version/version.go

@@ -1,3 +1,3 @@
 package version
 
-var Version = "0.6.2"
+var Version = "0.6.3"