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

The readme opened with a description of what Busser is built on rather
than what it does, and ended with a five step fork-and-branch list that
was the only development documentation in the repository. Nothing told a
contributor which Ruby to use, how to run either test suite, or how to
lint their change.

Lead instead with what Busser does and where it fits with Test Kitchen,
state the Ruby requirement, and document the plugin version syntax and
the BUSSER_ROOT default, neither of which appeared anywhere.

Move development material into CONTRIBUTING.md and cover setup, both
test suites and what each is for, the three linters CI runs, the commit
convention releases depend on, and the release process itself. It also
records why the plugin features sandbox GEM_HOME, since that is easy to
undo by accident and cost real time to diagnose.

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

Author: tas50

CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing to Busser
+
+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.
+
+## Getting set up
+
+Busser requires **Ruby 3.2 or newer**. Clone the repository and install the
+development dependencies:
+
+```bash
+git clone https://github.com/test-kitchen/busser.git
+cd busser
+bundle install
+```
+
+Run the CLI from the working tree with `bundle exec busser`.
+
+## Running the tests
+
+There are two suites, and `rake` runs both:
+
+```bash
+bundle exec rake test        # everything
+bundle exec rake unit        # minitest specs only
+bundle exec rake features    # cucumber features only
+```
+
+**Unit specs** live in `spec/` and cover library code directly. They use
+minitest's spec syntax with the `_()` expectation form:
+
+```ruby
+_(suite_path.to_s).must_match %r{/suites$}
+```
+
+The bare `suite_path.to_s.must_match` form was removed in minitest 6 and will
+not work.
+
+**Cucumber features** live in `features/` and drive the real `busser`
+executable through [aruba](https://github.com/cucumber/aruba), so they cover
+the CLI end to end. The step definitions are in `lib/busser/cucumber.rb`
+because plugin authors reuse them.
+
+Features that install plugins sandbox `GEM_HOME` into a temporary directory and
+strip bundler out of the environment, so a test never installs a gem into your
+bundle. If you add a step that shells out, be careful not to reintroduce
+bundler variables: modern RubyGems re-requires `bundler/setup` whenever
+`BUNDLER_SETUP` is present, which silently redirects `GEM_HOME` back at the
+bundle.
+
+## 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 | Major version bump |
+| `chore:`, `docs:`, `ci:`, `test:`, `refactor:` | No release |
+
+For example:
+
+```text
+fix: install plugins into GEM_HOME rather than the bundle
+feat: add a --verbose flag to plugin install
+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/version.rb` or edit `CHANGELOG.md` by
+hand; release-please owns both files.

README.md

@@ -2,39 +2,42 @@
 
 [![Gem Version](https://badge.fury.io/rb/busser.svg)](http://badge.fury.io/rb/busser)
 
-Busser is a test setup and execution framework designed to
-work on remote nodes whose system dependencies cannot be relied upon, except
-for an Omnibus installation of Chef. It uses a plugin architecture to add
-support for different testing strategies such minitest, cucumber, bash, etc.
+Busser runs your integration tests on the machine under test.
+
+It is built for remote nodes whose system dependencies cannot be relied upon,
+so it assumes very little about where it lands. Test frameworks are added as
+plugins, each a `busser-*` gem, which lets a single suite run bash scripts,
+minitest specs, RSpec examples or anything else a plugin knows how to execute.
+
+Busser is normally invoked for you by
+[Test Kitchen](https://github.com/test-kitchen/test-kitchen), which installs it
+on the instance under test and runs `busser test` as part of `kitchen verify`.
+You can also drive it directly, which is what the rest of this document covers.
 
 ## Status
 
 This software project is no longer under active development as it has no active maintainers. The software may continue to work for some or all use cases, but issues filed in GitHub will most likely not be triaged. If a new maintainer is interested in working on this project please come chat with us in #test-kitchen on Chef Community Slack.
 
-## Installation
+## Requirements
 
-Add this line to your application's Gemfile:
+Ruby 3.2 or newer.
 
-```ruby
-gem 'busser'
-```
-
-And then execute:
+## Installation
 
 ```bash
-bundle
+gem install busser
 ```
 
-Or install it yourself as:
+Or add it to your `Gemfile`:
 
-```bash
-gem install busser
+```ruby
+gem "busser"
 ```
 
 ## Usage
 
-Busser is driven by the `busser` command. Run `busser help` (or
-`busser help SUBCOMMAND`) for the full option list.
+Busser is driven by the `busser` command. Run `busser help`, or
+`busser help SUBCOMMAND`, for the full option list.
 
 ### Setting up
 
@@ -44,19 +47,22 @@ Create the Busser home directory, where plugins and suites are installed:
 busser setup
 ```
 
+By default this is `/opt/busser`. Set `BUSSER_ROOT` to put it elsewhere.
+
 ### Working with plugins
 
-Test frameworks are added as plugins, each packaged as a `busser-*` gem:
+Each test framework is a separate `busser-*` gem:
 
 ```bash
 busser plugin install busser-bash    # install a plugin
+busser plugin install busser-bash@0.3.0  # install a specific version
 busser plugin list                   # list installed plugins
 busser plugin create junit           # scaffold a new plugin
 ```
 
 ### Laying out tests
 
-Each plugin picks up the tests belonging to it, under a directory named after
+Each plugin picks up the tests belonging to it, from a directory named after
 the plugin inside the suite:
 
 ```text
@@ -81,15 +87,12 @@ busser test
 busser test bash minitest
 ```
 
-Busser is normally invoked for you by
-[Test Kitchen](https://github.com/test-kitchen/test-kitchen) rather than by
-hand -- Test Kitchen installs Busser on the instance under test and runs
-`busser test` as part of `kitchen verify`.
-
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Bug reports and pull requests are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the project, run the test
+suites, and format your commits.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).