Improve install script documentation

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - [#6](https://github.com/numbata/danger-pr-comment/pull/6): Setup danger workflows as an example - [@numbata](https://github.com/numbata).
 - [#1](https://github.com/numbata/danger-pr-comment/pull/1): Add comprehensive test suite with RSpec, Rubocop, and CI - [@dblock](https://github.com/dblock).
+* [#4](https://github.com/numbata/danger-pr-comment/pull/4): Improve install script documentation - [@dblock](https://github.com/dblock).
 
 ### Fixed
 

README.md

@@ -7,15 +7,51 @@ Reusable GitHub Actions workflows for running Danger and posting a PR comment fr
 ## Table of Contents
 
 - [Usage](#usage)
+  - [Prerequisites](#prerequisites)
   - [Quick Install](#quick-install)
   - [Manual Setup](#manual-setup)
-- [Requirements](#requirements)
-  - [Dangerfile report example](#dangerfile-report-example)
-- [Inputs](#inputs)
+- [Implementation Details](#implementation-details)
+  - [JSON Report Output](#json-report-output)
+    - [Shared Dangerfile](#shared-dangerfile)
+    - [Custom at_exit Hook](#custom-at_exit-hook)
+  - [Permissions](#permissions)
+  - [Inputs](#inputs)
+    - [danger-run.yml](#danger-runyml)
+    - [danger-comment.yml](#danger-commentyml)
 - [License](#license)
 
 ## Usage
 
+### Prerequisites
+
+Setup [Danger](https://github.com/danger/danger) in your repository.
+
+For example, the following `Gemfile` and `Dangerfile` install danger with the [danger-changelog plugin](https://github.com/dblock/danger-changelog).
+
+```ruby
+group :development, :test do
+  gem 'danger'
+  gem 'danger-changelog'
+  gem 'danger-pr-comment', require: false
+end
+```
+
+```
+# frozen_string_literal: true
+
+danger.import_dangerfile(gem: 'danger-pr-comment')
+
+changelog.check!
+```
+
+Run `bundle install` and `bundle exec danger` to make sure it works.
+
+```bash
+bundle exec danger
+
+Could not find the type of CI for Danger to run on.
+```
+
 ### Quick Install
 
 From your repository root:
@@ -24,7 +60,13 @@ From your repository root:
 curl -fsSL https://raw.githubusercontent.com/numbata/danger-pr-comment/main/scripts/install-workflows.sh | bash
 ```
 
-Use `--force` to overwrite existing workflow files. To target a specific directory:
+Use `--force` to overwrite existing workflow files `.github/workflows/danger.yml` and `.github/workflows/danger-comment.yml`: 
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/numbata/danger-pr-comment/main/scripts/install-workflows.sh | bash -s -- --force
+```
+
+To target a specific directory:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/numbata/danger-pr-comment/main/scripts/install-workflows.sh | bash -s -- --root /path/to/repo
@@ -42,8 +84,11 @@ on:
 
 jobs:
   danger:
-    uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@main
+    uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0
     secrets: inherit
+    with:
+      ruby-version: '3.4'
+      bundler-cache: true
 ```
 
 Create `.github/workflows/danger-comment.yml` in your repository:
@@ -62,32 +107,28 @@ permissions:
 
 jobs:
   comment:
-    uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@main
+    uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0
     secrets: inherit
 ```
 
-## Requirements
+## Implementation Details
 
-- Your repository must run `bundle exec danger` successfully.
-- Your Dangerfile must write a JSON report to `ENV['DANGER_REPORT_PATH']` (for example, via a custom `at_exit` hook or a shared Dangerfile).
-- The `Danger Comment` workflow requires explicit permissions. Reusable workflows cannot grant permissions to their callers. Required: `actions: read` (download artifacts from the Danger run), `issues: write` and `pull-requests: write` (create/update PR comments).
+Using danger-pr-comment solves the problem of needing special permissions to post a PR comment from contributions from forks. This is implemented by producing a JSON report during the PR, and reading the report in a separate workflow.
 
-### Dangerfile report example
+### JSON Report Output
 
-If you want a shared Dangerfile, add the gem and import it:
+Your Dangerfile must write a JSON report to `ENV['DANGER_REPORT_PATH']`.
 
-```ruby
-# Gemfile
-gem 'danger-pr-comment', require: false
-```
+#### Shared Dangerfile
 
 ```ruby
-# Dangerfile
-# Import danger-pr-comment for automatic danger report export
+# Import danger-pr-comment for automatic danger report export to JSON
 danger.import_dangerfile(gem: 'danger-pr-comment')
 ```
 
-Or add this to your project's `Dangerfile` (or a shared Dangerfile) to emit the JSON report yourself:
+See [Dangerfile](Dangerfile) for implementation details.
+
+#### Custom `at_exit` Hook
 
 ```ruby
 # Dangerfile
@@ -123,17 +164,21 @@ at_exit do
 end
 ```
 
-## Inputs
+### Permissions
+
+The `Danger Comment` workflow requires explicit permissions. Reusable workflows cannot grant permissions to their callers. Required: `actions: read` (download artifacts from the Danger run), `issues: write` and `pull-requests: write` (create/update PR comments).
+
+### Inputs
 
-`danger-run.yml` inputs:
+#### `danger-run.yml`
 
 - `ruby-version`: Ruby version for `ruby/setup-ruby`. Leave empty to use `.ruby-version`/`.tool-versions`.
 - `bundler-cache`: Enable Bundler caching (default `true`).
 - `danger-args`: Arguments passed to `bundle exec danger` (default `dry_run`).
 - `report-artifact-name`: Artifact name for the report (default `danger-report`).
 - `report-file`: Report filename (default `danger-report.json`).
 
-`danger-comment.yml` inputs:
+#### `danger-comment.yml`
 
 - `report-artifact-name`: Artifact name to download (default `danger-report`).
 - `report-file`: Report filename inside the artifact (default `danger-report.json`).

scripts/install-workflows.sh

@@ -69,8 +69,11 @@ on:
 
 jobs:
   danger:
-    uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@main
+    uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0
     secrets: inherit
+    with:
+      ruby-version: '3.4'
+      bundler-cache: true
 EOF
 
 write_file "$workflows_dir/danger-comment.yml" <<'EOF'
@@ -87,6 +90,6 @@ permissions:
 
 jobs:
   comment:
-    uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@main
+    uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0
     secrets: inherit
 EOF

spec/scripts/install_workflows_spec.rb

@@ -66,7 +66,7 @@ def danger_comment_yml_path
 
     it 'uses the reusable workflow' do
       content = File.read(danger_yml_path)
-      expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@main')
+      expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0')
     end
 
     it 'inherits secrets' do
@@ -94,7 +94,7 @@ def danger_comment_yml_path
 
     it 'uses the reusable workflow' do
       content = File.read(danger_comment_yml_path)
-      expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@main')
+      expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0')
     end
 
     it 'inherits secrets' do