Skip to content

Add a contributing guide - #28

Merged
jrwesolo merged 1 commit into
mainfrom
add-contributing-guide
Sep 16, 2026
Merged

jrwesolo merged 1 commit into
mainfrom
add-contributing-guide

Conversation

@jrwesolo

@jrwesolo jrwesolo commented Sep 16, 2026

Copy link
Copy Markdown
Owner

Adds CONTRIBUTING.md. There was no contributor documentation, so the setup, the test commands, and the conventions CI enforces were only discoverable by reading .github/workflows/ci.yml and the scripts next to it.

What it covers

  • Installing Cinc Workstation, with a pointer to TESTING.md for the pinned versions rather than duplicating them
  • The three test commands, and that integration tests need Docker
  • A table of what lives where, libraries/ against resources/, and which tests cover which
  • Why there are no ChefSpec tests, which otherwise reads as an oversight rather than a decision
  • Versioning, changelog format, what each CI job checks, and pull request expectations
  • That releases are automated and contributors need not tag or publish anything

Placement

The file is at the repository root rather than under .github/. GitHub honours either for its own UI prompt, but Supermarket's quality metric does not:

repo_contents = octokit_client.contents(repo)
!repo_contents.any? { |file| file.with_indifferent_access["name"] =~ /^contributing\.md$/i }

octokit_client.contents(repo) with no path lists the root only, so a file under .github/ would fail the metric.

Not in the published artifact

chefignore already carries CONTRIBUTING*, verified against the glob list directly: CONTRIBUTING.md is excluded alongside TESTING.md and CHANGELOG.md, while README.md, LICENSE, metadata.rb, libraries/ and resources/ still publish. The Supermarket metric reads the GitHub repository rather than the tarball, so excluding it costs nothing.

Testing

Documentation only, no cookbook code changed. cookstyle 17 files no offenses, rspec 66 examples 0 failures.

Resource names and paths used as examples were checked against resources/*.rb and the tree rather than written from memory. Link references and code fences verified balanced and all resolving. Spelling follows the repository's existing US convention, matching LICENSE and license 'MIT' in metadata.rb.

No version bump and no changelog entry, since nothing user-visible changed. This is the case the version job is built to skip.

Documents what a contributor needs that was previously only discoverable
by reading the workflow: which toolchain to install, how to run the
tests, where the library classes end and the resources begin, and what
the version job will check.

Also explains the absence of ChefSpec, which otherwise reads as an
oversight rather than a decision: the custom resources touch the real
filesystem at converge time, so exercising them under ChefSpec would
write to the host's own /etc/security/limits.conf.

The file sits at the repository root rather than under .github because
Supermarket's contributing_file quality metric matches
/^contributing\.md$/i against the root listing only.

chefignore already carries CONTRIBUTING*, so this stays out of the
published cookbook artifact alongside TESTING.md and CHANGELOG.md.
@jrwesolo
jrwesolo force-pushed the add-contributing-guide branch from ef556dc to afe562b Compare September 16, 2026 04:46
@jrwesolo
jrwesolo merged commit 091e8bd into main Sep 16, 2026
14 checks passed
@jrwesolo
jrwesolo deleted the add-contributing-guide branch September 16, 2026 04:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant