feat: add project docs and default product_name to cinc

ramereth · ramereth · commit 1e2c3e48c844 · 2026-04-20T13:13:45.000-07:00
- Rewrite README.md with full usage and configuration docs
- Add CHANGELOG.md scaffold for 0.1.0
- Add CODEOWNERS pointing to @cinc-project/maintainers
- Add CONTRIBUTING.md with release process
- Default product_name to 'cinc' in CincBase (uses modern install path)
- Update specs to match new product_name default

Signed-off-by: Lance Albertson &lt;lance@osuosl.org&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,13 @@
+# Kitchen-cinc Change Log
+
+## 0.1.0 (Unreleased)
+
+- Initial release of kitchen-cinc gem
+- Cinc Infra provisioner (`cinc_infra`) using cinc-client in local mode
+- Cinc Solo provisioner (`cinc_solo`)
+- Cinc Apply provisioner (`cinc_apply`)
+- Cinc Target provisioner (`cinc_target`) for remote execution (Cinc 19.0.0+)
+- Cinc Zero provisioner (`cinc_zero`) as deprecated alias for `cinc_infra`
+- Policyfile support with auto-detection
+- Berkshelf fallback support
+- Omnitruck-based package installation via `omnitruck.cinc.sh`
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -0,0 +1 @@
+@cinc-project/maintainers
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,14 @@
+# Release Process
+
+This release process applies to all Cinc Project Test Kitchen plugins, but each project may have additional requirements.
+
+1. Perform a diff between main and the last released version. Determine whether included MRs justify a patch, minor or major version release.
+2. Check out the main branch of the project being prepared for release.
+3. Branch into a release-branch of the form `150_release_prep`.
+4. Modify the `cinc_version.rb` file to specify the version for releasing.
+5. Run `rake changelog` to regenerate the changelog.
+6. `git commit` the `cinc_version.rb` and `CHANGELOG.md` changes to the branch and setup an MR for them. Allow the MR to run any automated tests and review the CHANGELOG for accuracy.
+7. Merge the MR to main after review.
+8. Switch your local copy to the main branch and `git pull` to pull in the release preparation changes.
+9. Run `rake release` on the main branch.
+10. Modify the `cinc_version.rb` file and bump the patch or minor version, and commit/push.
diff --git a/README.md b/README.md
@@ -1,2 +1,250 @@
 # kitchen-cinc
-A Test Kitchen provisioner for omnibus Cinc Clinet
+
+A Test Kitchen provisioner for [Cinc Client](https://cinc.sh/) (the community distribution of Chef Infra Client) that downloads and installs omnibus packages via the [Cinc omnitruck API](https://omnitruck.cinc.sh/).
+
+## Overview
+
+This Test Kitchen plugin provides provisioners that automatically download and install the desired version of Cinc Client on your test instances. This allows you to test your cookbooks against different Cinc versions without pre-installing Cinc on your images.
+
+## Installation
+
+**Note:** This gem will ship as part of Cinc Workstation. If you're using Cinc Workstation, no additional installation is necessary.
+
+For standalone installation, add this line to your Gemfile:
+
+```ruby
+gem "kitchen-cinc"
+```
+
+Then execute:
+
+```shell
+bundle install
+```
+
+Or install it directly:
+
+```shell
+gem install kitchen-cinc
+```
+
+## Usage
+
+### Available Provisioners
+
+This gem provides five provisioners:
+
+- **`cinc_infra`** — Modern Cinc Client provisioner using local mode (recommended)
+- **`cinc_zero`** — Deprecated alias for `cinc_infra` (maintained for backward compatibility)
+- **`cinc_solo`** — Cinc Solo provisioner (note: does not support parallel converge)
+- **`cinc_apply`** — Cinc Apply provisioner for running individual recipes
+- **`cinc_target`** — Cinc Target Mode provisioner (requires Cinc 19.0.0+, Train-based transport)
+
+### Basic Configuration
+
+To use the Cinc Infra provisioner in your `kitchen.yml`:
+
+```yaml
+provisioner:
+  name: cinc_infra
+```
+
+### Complete Example
+
+```yaml
+---
+driver:
+  name: vagrant
+
+provisioner:
+  name: cinc_infra
+  product_name: cinc
+  install_strategy: always
+  channel: stable
+
+platforms:
+  - name: ubuntu-24.04
+  - name: almalinux-9
+
+suites:
+  - name: default
+    run_list:
+      - recipe[my_cookbook::default]
+```
+
+### Docker (Dokken) Example
+
+```yaml
+---
+driver:
+  name: dokken
+  privileged: true
+  chef_image: cincproject/cinc
+  chef_version: latest
+
+provisioner:
+  name: cinc_infra
+  product_name: cinc
+
+transport:
+  name: dokken
+
+platforms:
+  - name: ubuntu-24.04
+    driver:
+      image: dokken/ubuntu-24.04
+      pid_one_command: /bin/systemd
+
+  - name: almalinux-9
+    driver:
+      image: dokken/almalinux-9
+      pid_one_command: /usr/lib/systemd/systemd
+```
+
+### Configuration Options
+
+#### `product_name`
+
+- **Type:** String
+- **Default:** `cinc`
+- **Description:** The product to install. Set to `cinc` for Cinc Client or `cinc-workstation` for Cinc Workstation.
+
+#### `product_version`
+
+- **Type:** String
+- **Default:** `latest`
+- **Description:** The version of Cinc Client to install. Can be a specific version (e.g., `19.2.12`) or `latest`.
+
+#### `channel`
+
+- **Type:** String/Symbol
+- **Default:** `stable`
+- **Options:** `stable`, `current`
+- **Description:** The release channel to install from.
+
+#### `install_strategy`
+
+- **Type:** String
+- **Default:** `once`
+- **Options:** `once`, `always`
+- **Description:** When to install Cinc. `once` only installs if not present, `always` reinstalls on every converge.
+
+#### `download_url`
+
+- **Type:** String
+- **Default:** none
+- **Description:** Override the download URL for custom package locations or air-gapped environments.
+
+#### `checksum`
+
+- **Type:** String
+- **Default:** none
+- **Description:** SHA256 checksum to verify the downloaded package. Used with `download_url`.
+
+#### `platform`, `platform_version`, `architecture`
+
+- **Type:** String
+- **Default:** Auto-detected
+- **Description:** Explicitly specify platform details for package selection.
+
+#### `run_list`
+
+- **Type:** Array
+- **Default:** `[]`
+- **Description:** The Cinc run list to execute.
+
+#### `attributes`
+
+- **Type:** Hash
+- **Default:** `{}`
+- **Description:** Node attributes to set during the converge.
+
+#### `log_level`
+
+- **Type:** String
+- **Default:** `auto`
+- **Description:** Cinc log level. Set to `debug` for verbose output, or `auto` to let Cinc decide.
+
+#### `log_file`
+
+- **Type:** String
+- **Default:** none
+- **Description:** Path to write the Cinc log file on the test instance.
+
+#### `multiple_converge`
+
+- **Type:** Integer
+- **Default:** `1`
+- **Description:** Number of times to run converge. Useful with `enforce_idempotency`.
+
+#### `enforce_idempotency`
+
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** When `true`, fails the run if the second converge makes changes. Requires `multiple_converge` >= 2.
+
+#### `deprecations_as_errors`
+
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** Treat Cinc deprecation warnings as errors.
+
+### Policyfile Support
+
+kitchen-cinc auto-detects `Policyfile.rb` in your cookbook directory and uses it for dependency resolution. You can also configure it explicitly:
+
+```yaml
+provisioner:
+  name: cinc_infra
+  policyfile_path: path/to/Policyfile.rb
+  policy_group: local
+  always_update_cookbooks: true
+```
+
+### Berkshelf Support
+
+If no Policyfile is found, kitchen-cinc will fall back to Berkshelf if a `Berksfile` is present:
+
+```yaml
+provisioner:
+  name: cinc_infra
+  berksfile_path: path/to/Berksfile
+  always_update_cookbooks: true
+```
+
+### Path Configuration
+
+All paths are auto-calculated if not specified:
+
+- `data_path` — Path to data directory
+- `data_bags_path` — Path to data bags
+- `environments_path` — Path to environments
+- `nodes_path` — Path to node definitions
+- `roles_path` — Path to roles
+- `clients_path` — Path to clients
+- `encrypted_data_bag_secret_key_path` — Path to encryption key
+
+## Development
+
+### Running Tests
+
+```shell
+bundle install
+bundle exec rake          # Run all tests and linting
+bundle exec rake spec     # Run unit tests only
+bundle exec rake lint     # Run Cookstyle linting only
+```
+
+### Integration Tests
+
+```shell
+# Vagrant
+KITCHEN_YAML=kitchen.yml bundle exec kitchen test
+
+# Docker (Dokken)
+KITCHEN_YAML=kitchen.dokken.yml bundle exec kitchen test
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) for details.
diff --git a/lib/kitchen/provisioner/cinc_base.rb b/lib/kitchen/provisioner/cinc_base.rb
@@ -115,9 +115,9 @@ class CincBase < Base
       # Modern configuration options (RFC 091 equivalent for Cinc)
       #
 
-      # Setting product_name to nil. It is currently the pivot point
-      # between the two install paths (Mixlib::Install::ScriptGenerator and Mixlib::Install)
-      default_config :product_name
+      # Default product_name to "cinc" so that the modern Mixlib::Install
+      # code path is used automatically.
+      default_config :product_name, "cinc"
 
       default_config :product_version, :latest
 
diff --git a/spec/kitchen/provisioner/cinc_base_spec.rb b/spec/kitchen/provisioner/cinc_base_spec.rb
@@ -134,8 +134,8 @@ def calculate_path(path, _opts = {})
       _(provisioner[:encrypted_data_bag_secret_key_path]).must_equal os_safe_root_path("/rooty/<calculated>/encrypted_data_bag_secret_key")
     end
 
-    it ":product_name default to nil" do
-      _(provisioner[:product_name]).must_be_nil
+    it ":product_name defaults to cinc" do
+      _(provisioner[:product_name]).must_equal "cinc"
     end
 
     it ":product_version defaults to :latest" do
@@ -188,8 +188,9 @@ def calculate_path(path, _opts = {})
       }
     end
 
-    it "returns nil if :require_chef_omnibus is falsey" do
+    it "returns nil if :require_chef_omnibus is falsey and product_name is nil" do
       config[:require_chef_omnibus] = false
+      config[:product_name] = nil
 
       installer.expects(:root).never
       installer.expects(:install_command).never
@@ -198,6 +199,7 @@ def calculate_path(path, _opts = {})
 
     describe "common behaviour" do
       before do
+        config[:product_name] = nil
         installer.expects(:root).at_least_once.returns("/opt/cinc")
         installer.expects(:install_command)
       end
@@ -554,6 +556,7 @@ def calculate_path(path, _opts = {})
 
     describe "for bourne shells" do
       before do
+        config[:product_name] = nil
         installer.expects(:root).at_least_once.returns("/opt/cinc")
         installer.expects(:install_command).returns("my_install_command")
       end
@@ -591,6 +594,7 @@ def calculate_path(path, _opts = {})
 
     describe "for powershell shells on windows os types" do
       before do
+        config[:product_name] = nil
         installer.expects(:root).at_least_once.returns("/opt/cinc")
         installer.expects(:install_command)
         platform.stubs(:shell_type).returns("powershell")
