The InSpec documentation is deployed on https://docs.chef.io/inspec/.
The fastest way to change the documentation is to edit a page on the GitHub website using the GitHub UI.
We also require contributors to include their DCO signoff
in the comment section of every pull request, except for obvious fixes. You can
add your DCO signoff to the comments by including Signed-off-by:, followed by
your name and email address, like this:
Signed-off-by: Julia Child <[email protected]>
See our blog post for more information about the DCO and why we require it.
After you've added your DCO signoff, add a comment about your proposed change, then click on the "Propose file change" button at the bottom of the page and confirm your pull request. The CI system will do some checks and add a comment to your PR with the results.
The Chef documentation team can normally merge pull requests within seven days. We'll fix build errors before we merge, so you don't have to worry about passing all the CI checks, but it might add an extra few days. The important part is submitting your change.
We use Hugo, Go, NPM, go-swagger, and jq. You will need Hugo 0.146 or higher installed and running to build and view our documentation properly.
To install Hugo, NPM, and Go on Windows and macOS:
- On macOS run:
brew tap go-swagger/go-swagger && brew install go-swagger hugo node go jq - On Windows run:
choco install hugo nodejs golang jq- See the Go-Swagger docs to install go-swagger
To install Hugo on Linux, run:
apt install -y build-essentialsudo apt-get install jqsnap install node --classicsnap install hugo --channel=extended- See the Go-Swagger docs to install go-swagger
-
(Optional) Install cspell
To be able to run the optional
make spellchecktask you'll need to installcspell:npm install -g cspell
Use one of the following methods to preview the documentation in inspec/chef-inspec-docs:
- submit a pull request
- run
make serve
When you submit a PR to inspec/chef-inspec-docs, Netlify builds the documentation
and add a notification to the GitHub pull request page. You can review your
documentation changes as they would appear on docs.chef.io.
- Run
make serve - go to http://localhost:1313
To clean your local environment, run make clean_all.
Release notes allow product engineering to communicate the list of features that are shipping in the builds being promoted to stable. Remember release notes aren't changelogs! The audience is our end-users, not other engineers. If you need a quick primer on what goes into good release notes, take a look at these excellent articles:
- The Life-Changing Magic of Writing Release Notes
- Let's All Appreciate These Great Release Notes Together
Capture the release notes on the Pending Release Notes wiki page. All edits should be completed and reviewed by a member of the Documentation Team before InSpec is promoted to stable. It's the responsibility of the individual development teams to ensure the release notes are updated with any features and breaking changes that ship when InSpec is promoted to the stable channel. We encourage teams to make updating these release notes part of their weekly rituals. Whatever is in the wiki page at promotion time is what goes out with the release!
During the promotion to the stable channel, the release notes will be extracted from the wiki page and published to an S3 bucket. The published release notes are then available at the following URLs:
https://docs.chef.io/release_notes_inspec/
https://packages.chef.io/release-notes/inspec/<VERSION>.md
We love getting feedback, questions, or comments.
Send an email to [email protected] for documentation bugs, ideas, thoughts, and suggestions. This email address isn't a support email address. If you need support, contact Chef Support.
Submit an issue to the InSpec repo for "important" documentation bugs that may need visibility among a larger group, especially in situations where a doc bug may also surface a product bug.