From 199944601ade9556b4b2ee1cae2ef54eea278713 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Sat, 20 Jun 2026 09:11:46 -0400 Subject: [PATCH] Update Jig docs for the move to voxpupuli/jig and refresh to current CLI The Jig scaffolding tool moved from github.com/avitacco/jig to github.com/voxpupuli/jig. Update every reference and bring the prose in line with Jig's current CLI (validated against the jig source). Repo move: - Point all avitacco/jig links and the go install path at voxpupuli/jig. Command/prose fixes: - Fix invalid commands in modules_publishing (jig module build, jig build build, jig module) to the actual jig build command. - Document the --skip-interview flag and its companion value flags on jig new module, and the template override precedence (the --template-dir flag, then the template_dir config key). The README's JIG_TEMPLATE_DIR env var does not reliably bind, so it is left out. Discoverability and naming: - Point the PDK page's jig 'alternative' entry at our own /ecosystem/latest/devkit/jig.html docs (keeping a repo link for source/releases) and capitalize the proper noun Jig. - Add a 'see installation and usage' pointer from the DevKit components list to the Scaffolding New Content with Jig page. - Add a cross-collection 'Scaffolding modules with Jig' entry to the core OpenVox Modules nav. Cross-collection links use absolute paths per CONTRIBUTING. jig validate / test unit / update: - migrating.md: map pdk update/validate/test unit to the jig commands, noting they wrap the underlying bundle exec calls (need bundle install). - linting.md: note jig validate runs validate + lint (not lint_fix). - unit_testing.md: add the run command (jig test unit, wrapping bundle exec rake spec). Closes #348 Co-Authored-By: Claude Opus 4.8 Signed-off-by: Michael Harp --- PDK.markdown | 2 +- _data/nav/openvox_8x.yml | 2 ++ docs/_ecosystem_8x/devkit/components.md | 3 ++- docs/_ecosystem_8x/devkit/jig.md | 18 ++++++++++----- docs/_ecosystem_8x/devkit/linting.md | 3 +++ docs/_ecosystem_8x/devkit/migrating.md | 23 +++++++++++--------- docs/_ecosystem_8x/devkit/unit_testing.md | 3 +++ docs/_openvox_8x/modules_publishing.markdown | 6 ++--- 8 files changed, 40 insertions(+), 20 deletions(-) diff --git a/PDK.markdown b/PDK.markdown index e7e6c71f8..f04e5b38e 100644 --- a/PDK.markdown +++ b/PDK.markdown @@ -26,4 +26,4 @@ OpenVox is compatible with PDK **3.4.0** and earlier for module development work The OpenVox community maintains tooling that replaces PDK workflows without requiring a commercial Puppet account: - **[VoxBox](https://github.com/voxpupuli/container-voxbox)** — A container image maintained by Vox Pupuli that includes rspec-puppet, Litmus, RuboCop, and other testing gems. It is the recommended way to run unit and acceptance tests for OpenVox modules in CI and local development. -- **[jig](https://github.com/avitacco/jig)** — A Go-based reimplementation of PDK. Ships as a single static binary with no Ruby runtime dependency and supports module scaffolding, building, and releasing. +- **[Jig](/ecosystem/latest/devkit/jig.html)** — A Go-based reimplementation of PDK. Ships as a single static binary with no Ruby runtime dependency and supports module scaffolding, building, and releasing. See the [jig project on GitHub](https://github.com/voxpupuli/jig) for source and releases. diff --git a/_data/nav/openvox_8x.yml b/_data/nav/openvox_8x.yml index 18b2f7b7d..99f376166 100644 --- a/_data/nav/openvox_8x.yml +++ b/_data/nav/openvox_8x.yml @@ -99,6 +99,8 @@ link: "modules_fundamentals.html" - text: Beginner's guide to writing modules link: "bgtm.html" + - text: Scaffolding modules with Jig + link: "/ecosystem/latest/devkit/jig.html" - text: Plugins in modules link: "plugins_in_modules.html" - text: Installing modules diff --git a/docs/_ecosystem_8x/devkit/components.md b/docs/_ecosystem_8x/devkit/components.md index e87a22e72..7b306e4bf 100644 --- a/docs/_ecosystem_8x/devkit/components.md +++ b/docs/_ecosystem_8x/devkit/components.md @@ -7,9 +7,10 @@ The Vox Pupuli developer toolkit is spread amongst many Ruby gems and other tool Most will be automatically pulled in via Bundler and the `Gemfile`, and some of the main ones will be listed at the bottom of this page for convenience. We'll focus on the tools that you may want to be aware of and install or use directly. -* [Jig](https://github.com/avitacco/jig) is useful for scaffolding content for new and existing modules. +* [Jig](https://github.com/voxpupuli/jig) is useful for scaffolding content for new and existing modules. All content it generates includes the appropriate barebones unit tests ready for you to fill out. It can also publish modules to the Puppet Forge. + See [Scaffolding New Content with Jig](jig.html) for installation and usage. * [ModuleSync](https://github.com/voxpupuli/modulesync) helps maintain a portfolio of many modules at once. It does this by maintaining both common static files (like contributing guides, licenses, or testing boilerplate) as well as templated files like `metadata.json` across multiple module repositories. This allows you to keep them all in a consistent state with minimal fuss. diff --git a/docs/_ecosystem_8x/devkit/jig.md b/docs/_ecosystem_8x/devkit/jig.md index 236c1ff2d..92975e34f 100644 --- a/docs/_ecosystem_8x/devkit/jig.md +++ b/docs/_ecosystem_8x/devkit/jig.md @@ -13,11 +13,11 @@ While OpenVox can technically load content this way in some cases, it's best to It's possible to create files and maintain the proper directory structure by hand and nothing prevents you from doing so. However, many people today prefer to use a scaffolding tool to maintain proper structure and consistency. -The tool we recommend for this today is [Jig](https://github.com/avitacco/jig). +The tool we recommend for this today is [Jig](https://github.com/voxpupuli/jig). ## Installing Jig -Download the latest release for your platform from the [releases page](https://github.com/avitacco/jig/releases). +Download the latest release for your platform from the [releases page](https://github.com/voxpupuli/jig/releases). Uncompress it and move the `jig` binary to a path like `/usr/local/bin`. {% include alert.html type="tip" title="macOS Security Alert" content="The packages are unsigned, so macOS won't open them by default. Run it once and cancel the warning dialog that tells you to trash it. @@ -29,7 +29,7 @@ This will place the compiled binary into `$GOPATH/bin`, which is likely to be `~ Ensure that location is in your `$PATH`. ```console -go install github.com/avitacco/jig@latest +go install github.com/voxpupuli/jig@latest ``` ## Creating a new module @@ -47,6 +47,9 @@ Source URL for the module []: https://http.cat/status/404 Created new module demo in /Users/ben.ford/Projects/demo ``` +To skip the interview and take the values from your config file, flags, or defaults instead, pass `--skip-interview` (or `-i`). +You can supply individual values with flags such as `--forge-user`, `--author`, `--license`, `--summary`, and `--source`. + Jig will create the full directory structure with starter files for the main class, Hiera data, rspec initialization helpers, etc. ```console @@ -123,7 +126,7 @@ Jig can create other types of content for your module: * `transport` _(uncommon)_ * Creates a new [Resource API](https://github.com/puppetlabs/puppet-resource_api) transport and its associated files. -See [Jig's GitHub page](https://github.com/avitacco/jig) for full documentation. +See [Jig's GitHub page](https://github.com/voxpupuli/jig) for full documentation. ## Configuring Jig @@ -148,7 +151,12 @@ To customize them, you'd dump them to disk and then edit as you like. jig templates dump ~/.config/jig/templates ``` -To use your new templates, add this directory to your Jig config file. +Any template found in your directory takes precedence over the embedded default, and any template you don't override falls back to the embedded version, so you only need to include the files you want to change. + +To tell Jig where your templates live, use either of the following: + +* the `--template-dir` (`-t`) flag on `jig new`, which takes precedence, or +* the `template_dir` key in your Jig config file. ----- diff --git a/docs/_ecosystem_8x/devkit/linting.md b/docs/_ecosystem_8x/devkit/linting.md index e5d0a53c3..95741a4cc 100644 --- a/docs/_ecosystem_8x/devkit/linting.md +++ b/docs/_ecosystem_8x/devkit/linting.md @@ -31,6 +31,9 @@ manifests/init.pp:10:manifest_whitespace_double_newline_end_of_file:ERROR:there Try running the `lint_fix` task instead and you'll see most or all of the offenses marked as `FIXED` instead of `ERROR` or `WARNING` indicating that it has fixed the source files for you. Some offenses cannot be fixed automatically and you may have to update them yourself. +If you use Jig, `jig validate` runs the `validate` and `lint` tasks together (equivalent to `bundle exec rake validate lint`). +It doesn't run `lint_fix`, so run the `lint_fix` task directly when you want automatic fixes. + ### Configuring the Puppet linter You can disable any of the checks you like by creating a `.puppet-lint.rc` file in the root of your module. diff --git a/docs/_ecosystem_8x/devkit/migrating.md b/docs/_ecosystem_8x/devkit/migrating.md index 6d00dde86..7ef86a657 100644 --- a/docs/_ecosystem_8x/devkit/migrating.md +++ b/docs/_ecosystem_8x/devkit/migrating.md @@ -16,15 +16,18 @@ If you get an error about a command not being available, you probably just need {% include alert.html type="tip" content="There are a few exceptions to this pattern. For example, Jig is an installed package and VoxBox is a Docker container." %} -| You used to type... | Now you type... | -|---------------------|----------------------------------| -| `pdk new module` | `jig new module` | -| `pdk new class` | `jig new class` | -| `pdk build` | `jig build` | -| `pdk release` | `jig release` | -| `pdk convert` | _not needed_ | -| `pdk update` | `bundle exec msync update` | -| `pdk validate` | `bundle exec rake validate lint` | -| `pdk test unit` | `bundle exec rake spec` | +| You used to type... | Now you type... | +|---------------------|------------------| +| `pdk new module` | `jig new module` | +| `pdk new class` | `jig new class` | +| `pdk build` | `jig build` | +| `pdk release` | `jig release` | +| `pdk convert` | _not needed_ | +| `pdk update` | `jig update` | +| `pdk validate` | `jig validate` | +| `pdk test unit` | `jig test unit` | + +`jig update`, `jig validate`, and `jig test unit` are thin wrappers around `bundle exec msync update`, `bundle exec rake validate lint`, and `bundle exec rake spec` respectively, so they still need the module's gems installed (`bundle install`). +You can keep running the underlying `bundle exec` commands directly if you prefer. Browse through the individual subpages of this Developer Tooling section to learn more about each component. diff --git a/docs/_ecosystem_8x/devkit/unit_testing.md b/docs/_ecosystem_8x/devkit/unit_testing.md index cdb389df1..94a685285 100644 --- a/docs/_ecosystem_8x/devkit/unit_testing.md +++ b/docs/_ecosystem_8x/devkit/unit_testing.md @@ -49,6 +49,9 @@ end This uses [`facterdb`](https://github.com/voxpupuli/facterdb) and [`rspec-puppet-facts`](https://github.com/voxpupuli/rspec-puppet-facts) to run your the test on all supported platforms from the module's `metadata.json`. +To run your unit tests, use `jig test unit`, which wraps `bundle exec rake spec`. +Either form needs the module's gems installed, so run `bundle install` first. + If you'd like to constrain a test run to only a specific OS or OS release, you can do so with environment variables: ```console diff --git a/docs/_openvox_8x/modules_publishing.markdown b/docs/_openvox_8x/modules_publishing.markdown index 0b7c2a3ae..e4a469aa8 100644 --- a/docs/_openvox_8x/modules_publishing.markdown +++ b/docs/_openvox_8x/modules_publishing.markdown @@ -103,11 +103,11 @@ junit/ tmp/ ``` -The `.pdkignore` file excludes files during `jig module build` only. +The `.pdkignore` file excludes files during `jig build` only. For example, you might want spec tests in your source control but not in your module package, so you would list them in `.pdkignore`. To prevent files, such as those in temporary directories, from ever being checked into Git, use `.gitignore`. -If you have both a `.pdkignore` and a `.gitignore` file, the `jig module` command uses the `.pdkignore` file. +If you have both a `.pdkignore` and a `.gitignore` file, the `jig build` command uses the `.pdkignore` file. ### Removing symlinks from your module @@ -143,7 +143,7 @@ Related topics: To upload your module to the Forge, you first must build the module package. -1. From the command line in your module's root directory, run `jig build build`. This command generates a `.tar.gz` package and saves it in the module's `pkg/` subdirectory. +1. From the command line in your module's root directory, run `jig build`. This command generates a `.tar.gz` package and saves it in the module's `pkg/` subdirectory. For example: