docs: rewrite the readme and add a contributing guide (#83)

The README was a mix of usage docs and stale notes, with links pointing at
`master`. It is now just what a user of the plugin needs: what it does, what it
requires, where tests go, and what a passing test looks like. Everything a
contributor needs moved to CONTRIBUTING.md, modelled on the one in
test-kitchen/busser -- how to set the project up, how to run the suite, the
linters CI runs, and the Conventional Commits convention release-please reads.

Every development dependency now carries a version floor at its current major,
so a resolver cannot quietly pick an ancient release: cookstyle 9, aruba 2.4,
cucumber 11.1, rake 13.4, serverspec 2.43, simplecov 1.1.

Test tooling brought up to date:

* `.rubocop.yml` targeted Ruby 3.1 while the gemspec requires 3.2.
* The `After` hook setting `Cucumber.wants_to_quit` is replaced by cucumber's
  own `--fail-fast`, which is the supported way to stop at the first failure.
* `-x` (`--expand`) is dropped; it only affects Scenario Outline output and
  there are no outlines here.

Two notes specific to this repository:

**CONTRIBUTING.md was not a contributing guide.** It held a notice recommending
kitchen-verifier-shell instead of this plugin. That is useful information for a
user, not a contributor, so it has moved into the README's Status section
alongside the archival notice, and CONTRIBUTING.md is now an actual contributing
guide.

**The documented file layout was wrong.** The README said the glob was
`serverspec/*/*_spec.rb` and that specs must sit exactly one directory deep. The
runner has used `**/*_spec.rb` since the RSpec 3 support landed, so any depth
works and the `localhost/` directory is convention rather than a requirement.

`.tailor` is removed. It configured the tailor gem, unmaintained since 2014 and
not in the bundle, so the file did nothing.

Signed-off-by: Tim Smith <tsmith84@proton.me>

Author: tas50

.rubocop.yml

@@ -3,7 +3,7 @@ require:
   - cookstyle/chefstyle
 
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
   Exclude:
     - "vendor/**/*"
     - "spec/**/*"

.tailor

@@ -1,6 +1,104 @@
-# Notice
+# Contributing to busser-serverspec
 
-You should use [Kitchen::Verifier::Shell](https://github.com/higanworks/kitchen-verifier-shell) + [Serverspec](http://serverspec.org/) instead of Busser::RunnerPlugin::Serverspec.
+Thanks for taking the time to contribute. This document covers how to get the
+project running locally, how to check your work before opening a pull request,
+and the commit convention releases depend on.
 
-* [Official Document](https://github.com/test-kitchen/test-kitchen/pull/741) (This PR has been merged. You can use this with Test Kitchen 1.5.0)
-* [Cookbook testing by Serverspec with Shell Verifier of Test Kitchen](http://www.creationline.com/en/lab/12161) ([Japanese](http://www.creationline.com/lab/12161))
+## Getting set up
+
+This plugin requires **Ruby 3.2 or newer**. Clone the repository and install the
+development dependencies:
+
+```bash
+git clone https://github.com/test-kitchen/busser-serverspec.git
+cd busser-serverspec
+bundle install
+```
+
+## Running the tests
+
+`rake` runs the whole suite:
+
+```bash
+bundle exec rake test
+```
+
+The tests are [cucumber](https://cucumber.io) features in `features/`. They
+drive the real `busser` executable through
+[aruba](https://github.com/cucumber/aruba) rather than calling the plugin's
+classes, so they cover it end to end: install the plugin into a throwaway
+Busser root, write a suite, run it, and check what came out. The step
+definitions they use are published by busser itself, in `lib/busser/cucumber.rb`.
+
+### How the feature sandbox works
+
+Features that install the plugin sandbox `GEM_HOME` into a temporary directory
+and strip bundler out of the environment, so a run never installs a gem into
+your bundle. Two details matter if you add or change one:
+
+* **Do not reintroduce bundler variables.** RubyGems re-requires
+  `bundler/setup` whenever `BUNDLER_SETUP` is present, and bundler then resets
+  `Gem.dir` to the bundle. Plugins install into `vendor/bundle` instead of the
+  sandbox, and the assertions that look in `GEM_HOME` fail. The
+  `a non bundler environment` step exists to clear this.
+* **The plugin is installed from the working tree.** With bundler out of the
+  way, `busser plugin install` would fetch the last release from RubyGems and
+  run *its* postinstall — so the suite would pass on code that is not in your
+  branch. The `this plugin is installed from the working tree` step builds the
+  gem from the gemspec and installs it into the sandbox first, which is what
+  makes the features test your change.
+
+## Linting
+
+CI runs three linters, all of which you can run locally:
+
+```bash
+bundle exec cookstyle --chefstyle   # Ruby
+yamllint --strict .                 # YAML
+markdownlint-cli2 "**/*.md" "!**/CHANGELOG*.md"
+```
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org).
+Releases are automated, and the commit subject on `main` is what decides the
+next version number and what appears in the changelog.
+
+Pull requests are **squash merged, so the pull request title becomes that
+subject**. A CI check enforces the format on the title; the individual commits
+on your branch are not checked.
+
+| Prefix | Effect on the next release |
+| --- | --- |
+| `fix:` | Patch version bump |
+| `feat:` | Minor version bump |
+| `feat!:`, or a `BREAKING CHANGE:` footer | Minor bump, until this gem reaches 1.0 |
+| `chore:`, `docs:`, `ci:`, `test:`, `refactor:` | No release |
+
+For example:
+
+```text
+fix: install the plugin into GEM_HOME rather than the bundle
+feat: support a Gemfile alongside the suite
+ci: pin the shared workflow to a release
+```
+
+## Opening a pull request
+
+1. Fork the repository and create a branch for your change.
+2. Add or update tests. A bug fix should come with a test that fails without it.
+3. Run `bundle exec rake test` and the linters above.
+4. Open a pull request with a Conventional Commits title.
+
+## Releases
+
+Releases are handled by
+[release-please](https://github.com/googleapis/release-please). It watches
+commits landing on `main` and keeps a release pull request open with the next
+version number and the accumulated changelog. Merging that pull request tags the
+release and publishes the gem to RubyGems and GitHub Packages.
+
+Maintainers do not bump `lib/busser/serverspec/version.rb` or edit
+`CHANGELOG.md` by hand; release-please owns both files. This gem is still pre-1.0, so
+`bump-minor-pre-major` is set and a breaking change takes the minor rather than
+graduating it to 1.0.

CONTRIBUTING.md

@@ -3,17 +3,17 @@ source "https://rubygems.org"
 gemspec
 
 group :cookstyle do
-  gem "cookstyle", ">= 9.0.0"
+  gem "cookstyle", ">= 9.0"
 end
 
 group :test do
-  gem "aruba", ">= 2.0"
-  gem "base64" # cucumber needs it; not a default gem on Ruby 4.0
+  gem "aruba", ">= 2.4"
+  gem "base64", ">= 0.3" # cucumber needs it; not a default gem on Ruby 4.0
   gem "cucumber", ">= 11.1"
-  gem "rake"
+  gem "rake", ">= 13.4"
   gem "serverspec", ">= 2.43"
 end
 
 group :development do
-  gem "simplecov"
+  gem "simplecov", ">= 1.1"
 end

Gemfile

@@ -1,72 +1,110 @@
-# Busser::RunnerPlugin::Serverspec
+# busser-serverspec
 
+[![Gem Version](https://badge.fury.io/rb/busser-serverspec.svg)](https://badge.fury.io/rb/busser-serverspec)
 
-A Busser runner plugin for Serverspec
+A [Busser](https://github.com/test-kitchen/busser) runner plugin that runs
+[Serverspec](https://serverspec.org) tests as integration tests.
+
+Busser installs Serverspec on the machine under test the first time a suite
+runs, then executes the suite's `serverspec` directory against it. Because the
+tests run on the machine itself, they use Serverspec's `exec` backend rather
+than SSH.
 
 ## Status
 
-This Gem has now been archived. No active maintainers have come forward in the past 5 years and the original maintainer has since pulled the plugin.
+This gem has been archived. No active maintainers have come forward in the past
+five years and the original maintainer has since pulled the plugin.
+
+We recommend moving to a maintained project for similar functionality, or
+building and running the gem yourself. In particular,
+[kitchen-verifier-shell](https://github.com/higanworks/kitchen-verifier-shell)
+with Serverspec covers the same ground and is configured directly in your
+`kitchen.yml`.
+
+## Requirements
 
-We recommend moving to a maintained project for similar functionality or building and running the Gem yourself.
+Ruby 3.2 or newer, and busser 0.9.0 or newer.
 
-## Installation and Setup
+## Installation
 
-Put this into your `kitchen.yml`:
+Select the Busser verifier in your `kitchen.yml`:
 
 ```yaml
 verifier:
   name: busser
 ```
 
-You may also look at the Busser [plugin usage][plugin_usage] page.
+Busser then installs the plugin for you when the suite runs. To install it by
+hand:
+
+```bash
+busser plugin install busser-serverspec
+```
 
 ## Usage
 
-Please put test files into [COOKBOOK]/test/integration/[SUITES]/serverspec/
-
-```cookbook
-`-- test
-    `-- integration
-        `-- default
-            `-- serverspec
-                |-- Gemfile
-                |-- localhost
-                |   `-- httpd_spec.rb
-                `-- spec_helper.rb
+Put your specs in a subdirectory of the suite's `serverspec` directory:
+
+```text
+test
+`-- integration
+    `-- default              # suite name
+        `-- serverspec
+            |-- Gemfile          # optional
+            |-- spec_helper.rb
+            `-- localhost
+                `-- httpd_spec.rb
 ```
 
-`Gemfile` is optional. You can specify installing Serverspec version and install the gems you need.
-
-## Note
+Specs are collected recursively as `**/*_spec.rb`, so any depth works; the
+`localhost/` directory above is convention, not a requirement. The separator is
+an underscore — `_spec.rb`, not `-spec.rb`. The suite directory is also added to
+the load path and set as RSpec's default path, so `require "spec_helper"` works
+without a relative path.
 
-### File Matching
+```ruby
+require "spec_helper"
 
-The globbing pattern to match files is `"serverspec/*/*_spec.rb"`.
-You need to use `"_spec.rb"` (underscore), not `"-spec.rb"` (minus).
+describe command("echo hello") do
+  its(:exit_status) { should eq 0 }
+  its(:stdout) { should eq "hello\n" }
+end
+```
 
-### Specify Serverspec version
+### Backend
 
-If you have to specify the Serverspec version, you can use Gemfile. Example Gemfile:
+The tests run on the machine under test, after Test Kitchen has logged in, so
+the `exec` backend is the right one:
 
-```Gemfile
-source 'https://rubygems.org'
-gem 'serverspec', '< 2.0'
+```ruby
+require "serverspec"
+set :backend, :exec
 ```
 
-### Serverspec backend
+Do not use `set :backend, :ssh` — that would have Serverspec connect back out
+over the network from a machine that is already the target.
+
+### Pinning Serverspec
+
+A `Gemfile` in the suite directory is `bundle install`ed before the run, which
+is how you pin a particular Serverspec version:
+
+```ruby
+source "https://rubygems.org"
+
+gem "serverspec", "~> 2.43"
+```
 
-It runs on a target server for testing after ssh log in it.
-So you need to specify `set :backend, :exec` not `set :backend, :ssh` (Serverspec v2).
-If you use Serverspec v1, you must specify `include SpecInfra::Helper::Exec` not `include SpecInfra::Helper::Ssh`.
+Without one, the plugin installs Serverspec 2.43 or newer.
 
-## Authors
+## Contributing
 
-Created and maintained by [HIGUCHI Daisuke][author] (<d-higuchi@creationline.com>)
+Bug reports and pull requests are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the project, run the test
+suite, and format your commits.
 
 ## License
 
-Apache 2.0 (see [LICENSE][license])
+Apache License 2.0. See [LICENSE](LICENSE).
 
-[author]:           https://github.com/cl-lab-k
-[license]:          https://github.com/test-kitchen/busser-serverspec/blob/master/LICENSE
-[plugin_usage]:     https://kitchen.ci/docs/verifiers/serverspec/
+Originally created by [HIGUCHI Daisuke](https://github.com/cl-lab-k).

README.md

@@ -2,7 +2,7 @@ require "bundler/gem_tasks"
 require "cucumber/rake/task"
 
 Cucumber::Rake::Task.new(:features) do |t|
-  t.cucumber_opts = ["features", "-x", "--format progress"]
+  t.cucumber_opts = ["features", "--format progress", "--fail-fast"]
 end
 
 desc "Run all test suites"

Rakefile

@@ -7,7 +7,10 @@
 if ENV["COVERAGE"]
   require "simplecov"
   SimpleCov.command_name "features"
-  SimpleCov.start
+  SimpleCov.start do
+    add_filter "/features/"
+    add_group "Libraries", "/lib/"
+  end
 end
 
 # aruba 2 dropped @aruba_timeout_seconds; setting it in a Before hook is a
@@ -17,13 +20,6 @@
   config.exit_timeout = 120
 end
 
-After do |s|
-  # Tell Cucumber to quit after this scenario is done - if it failed.
-  # This is useful to inspect the 'tmp/aruba' directory before any other
-  # steps are executed and clear it out.
-  Cucumber.wants_to_quit = true if s.failed?
-end
-
 # The sandboxed features shell out to `busser plugin install <this plugin>`, and
 # two things have to hold for that to exercise this checkout:
 #