Skip to content

Latest commit

 

History

History
290 lines (248 loc) · 18.4 KB

CONTRIBUTING.md

File metadata and controls

290 lines (248 loc) · 18.4 KB

Contributing

Use the common commit process for commit messages, PR titles and dependency updates.

Make and workflow conventions

Follow the Hoverkraft Makefile and workflow layout. Use annotated Make targets for generated help and a shared run_linter helper for lint and lint-fix. The container uses Linux amd64, the caller's UID/GID, and the checkout's absolute path for its workspace. A failed image build stops the command before linting.

make help lists commands. make lint-fix applies supported automatic fixes; make lint docs/ limits linting to matching paths. Positional filters are accepted only for lint commands; unknown standalone targets still fail. make ci runs lint-fix and unit tests locally. VM integration tests run in hosted action-test workflows.

Internal __main-ci.yml and __pull-request-ci.yml call __shared-ci.yml. Main supports branch and tag pushes and manual runs; PR CI also supports merge queues. Both cancel superseded runs for the same workflow and ref. Each public action has a dedicated test workflow, with backend and scenario variants inside it. Other actions provide fixture setup or cleanup; assertions verify the action named by the workflow. Consumers compose the same actions in their VM jobs. Use test-action- caller IDs in __shared-ci.yml, following ci-github-common. Keep additional JavaScript unit checks in the owning action's workflow through ci-github-nodejs/actions/test, using the action's directory as working-directory, alongside its integration scenarios. Shared CI composes those workflows; make test is a local convenience. Name test steps Arrange - ..., Act - ... and Assert - ...; place assertions next to the behavior they verify. Use explicit Cleanup - ... steps with always() for fixture teardown, even when an action or assertion fails. Repeat Act/Assert pairs for independent cases sharing the same fixture; repeated calls may form one Act phase when testing report isolation. Workflows start with permissions: {} and grant only the permissions required by each job. Keep Actions pinned and step names descriptive.

Repository automation

Keep the five Hoverkraft maintenance workflows alongside the CI entrypoints:

  • __greetings.yml welcomes first-time contributors on new issues and PRs.
  • __need-fix-to-issue.yml turns fix markers into issues after main pushes, or for a manually selected commit range.
  • __semantic-pull-request.yml validates Conventional Commit PR titles.
  • __renovate.yml runs dependency updates weekly and on manual dispatch.
  • __stale.yml manages inactive issues and PRs daily using shared defaults.

The four collaboration workflows reuse the pinned ci-github-common workflows. Renovate uses the organization's CI_BOT_APP_CLIENT_ID Actions variable and CI_BOT_APP_PRIVATE_KEY Actions secret. Its GitHub App must be installed on this repository with the permissions requested by the token-generation step. The internal tests/fixture/prepare-vm action prepares synthetic VM configurations without starting guests or asserting action behavior. Keep its Ubuntu image URL and checksum aligned with tests/fixture/lima.yml.

The Lima version is maintained in actions/vm/create/action.yml. Keep the token scoped to this repository and the repository configuration in .github/renovate.json. Dependabot owns Actions, Dockerfile, Python and action test-package updates. Its npm directory glob /actions/*/* matches the action package layout used by make test; Renovate owns Lima, Goss, the documentation image and the action .node-version files, grouping Node.js runtime updates in one pull request. It also maintains the Ansible fixture's .python-version and sanity image tag/digest within the selected Ansible Core series. Review the image series when upgrading Core.

Validation

Use Node.js 24.8 or later locally; hosted unit jobs use each action's .node-version. Run make test with Node.js's built-in test runner for focused validation and failure cases, make lint for the Hoverkraft containerized linter, and the hosted action-test workflows for actual VM behavior. PR CI verifies action outcomes across successful assertions, failed assertions and failed startup, without a consumer Makefile. It repeats tests on the same guest to verify independent reports, collects native Goss JUnit after assertion failures, and verifies action-owned parsing, summaries and artifact uploads. PR comments reuse stable titles; fork and Dependabot runs skip comments. Tests inspect native report files and GitHub artifacts directly, and check published summaries through PR comments when comments are enabled. Consumer workflows grant comment permissions and always schedule cleanup. Hosted scenarios are the primary checks for public action behavior. Unit tests call action modules directly where they add distinct coverage: input boundaries, process ownership, failed rollback or deletion, corrupted downloads, incomplete report transfers and report isolation after write failures. Keep native-format preservation and private-data checks. Avoid repeating successful or ordinary failed workflows with mocks, and assert outcomes instead of internal calls unless ordering or deadlines are part of the contract. A unit suite is justified by these additional cases, not by requiring one for every action.

Group JavaScript cases in named suite() blocks from node:test, with test() for each case. Mark phases with // Arrange, // Act and // Assert. Prepare fixtures and mocks before execution, then check results. For expected exceptions, define the deferred call in Act and evaluate it with assert.throws or await assert.rejects in Assert. Repeat labeled phases when a case verifies a sequence such as failure and recovery.

Each action owns a private package.json, lockfile, .node-version and tests/ directory. Development dependencies supply the same Toolkit helpers injected by the pinned GitHub Script action; production scripts receive them from the caller. For example, run npm --prefix actions/vm/create ci followed by npm --prefix actions/vm/create test for creation tests. Hosted unit jobs run npm run test:ci: the pretest:ci hook creates the coverage directory, then Node.js writes console results and coverage/lcov.info. Generated coverage files are gitignored. make test discovers the action packages, installs their locked test dependencies and runs each suite, stopping on failure. Keep reusable test helpers in tests/helpers/ and synthetic inputs in tests/fixture/. Keep single-use setup beside its tests; avoid adding test harnesses that parse action YAML or emulate the GitHub Script runtime. The public actions require no npm installation in consumer workflows.

__shared-ci.yml runs the dedicated workflows:

Workflow in .github/workflows/ Action Coverage
__test-actions-ansible-test.yml ansible/test Playbook and collection sanity success/failure, native reports
__test-actions-ansible-test-molecule.yml ansible/test-molecule Local success/failure/timeout cleanup; VM deployment, idempotence and reboot
__test-actions-vm-create.yml vm/create Lima and QEMU startup, usable SSH outputs, startup rollback before fallback cleanup
__test-actions-vm-test.yml vm/test Lima and QEMU Goss success, failure, empty suites, timeout and independent reports
__test-actions-vm-destroy.yml vm/destroy Lima and QEMU deletion, repeated deletion and unmanaged-data preservation

__test-actions-ansible-test.yml exercises playbook tests and collection sanity success/failure scenarios through maintained playbook execution and Ansible community testing actions. The role-only sanity fixture uses a pinned upstream container and explicit Python runtime; it contains no Python modules requiring a multi-version target matrix. It verifies native report publication after failures. Adjacent JavaScript only validates inputs and collects reports; upstream actions own test execution, collection Python setup and containers. Playbook tests use a temporary virtual environment and the built-in JUnit callback. Both Ansible playbook and Molecule actions own controller setup through actions/setup-python; python-version-file reuses the consumer's maintained pin. The hosted fixtures assert the interpreter actually executing the native playbook. Collection sanity owns its own runtime. Consumers supply their Ansible Core pin, Galaxy requirements and selected targets. Dependabot maintains upstream action pins and the fixture's requirements file. Linting remains in the separate linter workflow.

Releases and dependencies

Use Conventional Commits and a reviewed pull request. Publish semantic versions only after CI and consumer validation pass: major for incompatible contracts, minor for compatible features, patch for fixes. Consumers pin full commit SHAs; do not move release tags.

__prepare-release.yml applies the shared Conventional Commit release labels on pull requests. __release.yml runs every Monday at 08:25 UTC and supports manual dispatch. It runs the complete shared CI on the default branch, then plans and publishes a release for that run's exact commit using ci-github-publish. Runs from other branches or tags are skipped. No relevant changes means no publication; the manual force input bypasses only that no-changes guard, not CI or existing-tag checks.

To release on demand, run Internal - Release from the Actions tab with main selected, or use:

gh workflow run __release.yml --ref main

The release job authenticates with CI_BOT_APP_CLIENT_ID and CI_BOT_APP_PRIVATE_KEY; OPENAI_API_KEY supplies release-summary generation. These values can be provided through organization variables and secrets. The app needs repository contents write and pull request read permissions for publication. Its token allows the resulting tag push to trigger main CI.

Main CI runs on main and tag pushes, manual dispatch, and the weekly schedule. The weekly run validates the repository without updating documentation. After successful push or manual main CI, the shared release-actions workflow regenerates action documentation and opens or updates its documentation PR, using squash merging. Tag pushes and manual main CI runs refresh all action references. Internal __ workflows are excluded from generation. Documentation automation uses the same app, with contents, pull request and workflow write permissions. Successful main-branch documentation generation sends its artifact to the public documentation portal through public-docs/sync-docs-dispatcher.yml.

Renovate updates the Goss version and archive SHA-256 together using the github-release-attachments datasource. Review the Ubuntu image URL and SHA-256 together against the official release index when refreshing the fixture; boot the new image before merging. A dependency proposal is not evidence of compatibility.

Action and public workflow reference docs are generated by make docs using the stable CI Dokumentor Docker image pinned in the Makefile and maintained by Renovate. Install Docker and authenticate the GitHub CLI with gh auth login first. The container runs with your UID/GID and receives the token from gh auth token through GITHUB_TOKEN. Quoted patterns discover actions/**/action.{yml,yaml} and .github/workflows/!(__*).{yml,yaml} automatically, excluding internal workflows whose filenames start with __. Change metadata and regenerate; never hand-edit the generated reference. Keep usage guidance in the leading comments and input descriptions of each action.yml, so the generated action readme is self-contained.

Action runtime

Use the pinned actions/github-script runtime and pass its injected helpers into adjacent modules: core for outputs and status, exec for subprocesses, io for ordinary copies, directory creation and cleanup, and glob for local report discovery. Await helper calls so failures reach the action before it publishes outputs. Keep Node filesystem APIs for private temporary directories, permissions, ownership, exclusive writes/copies and atomic report publication. io.cp with force: false silently skips existing files; it cannot replace a copy that must fail on collision. VM report collection selects only the native goss.xml regular file. VM commands use GNU timeout through exec.exec, with silent, bounded output capture and literal stdin. The deadline also bounds child processes; output beyond 1 MiB is discarded and fails the command when it exits or times out. Pass inputs through step environment variables. Keep short, straightforward scripts inline in action.yml; retain adjacent modules for substantial code with complex validation, execution or cleanup behavior. Avoid wrapper files and phase dispatchers for simple step calls. This is a readability decision, not a fixed line-count rule. Resolve external imports from github.action_path, never the consumer checkout. Hosted workflows exercise inline action steps; unit tests call action modules directly with Toolkit helpers. Each action owns its operation:

  • actions/vm/create/ validates configuration, allocates private runtime directories, starts guests and rolls back failed startup.
  • actions/vm/test/ owns guest commands and file transfer in guest.cjs, executes Goss, collects native JUnit and publishes results.
  • actions/vm/_internal/runtime.cjs validates owned runtimes, identifies running guests and verifies deletion for Lima and QEMU. VmReference provides identity, ownership checks and presence detection. Testing uses that interface; VirtualMachine adds cleanup for creation rollback and explicit destruction. It contains no allocation or guest transport.
  • actions/vm/_internal/command.cjs bounds subprocess execution; workspace.cjs validates checkout paths.

Keep code shared only when multiple actions enforce the same safety contract: runtime ownership and verified cleanup, bounded and redacted command execution, or checkout-path containment. These rules stay consistent across their callers. Action-specific behavior stays with its owner, and test transport must not inherit cleanup. Startup rollback and explicit destruction use the same verified cleanup. The internal modules are not a public API. Keep modules executable with Node.js 24; no package installation or build is required. Dependencies point from action code to shared helpers. Shared helpers do not import action code; creation and destruction use the same teardown implementation.

Expose inputs and outputs for concrete consumer needs. Test actions publish reports and communicate success through their step outcome; they expose no report outputs. Only vm/create exports vm, name and ssh-config for subsequent operations. Use github.token for comments and native Ansible configuration for inventory and collection search paths. Integration tests must verify these effects without adding public options solely for testing.

Project artwork

The project logo and social preview use Hoverkraft's project template. Preserve its square geometry, wave and colors. The white icon combines connected infrastructure nodes with code brackets. The preview uses outlined Inter lettering so rendering does not depend on installed fonts. Keep the 1280 × 640 PNG export aligned with the SVG source. The preview embeds the logo geometry to remain self-contained; it is excluded from code duplication checks.

Opinionated VM verification

vm/test owns Goss installation, checksum verification, rendering, guest execution and native reporting. Renovate maintains the release and archive checksum together in actions/vm/test/goss.json; review both against the upstream release. Its hosted fixtures cover Lima success and QEMU success, failed assertions and empty suites. Goss state checks should be read-only.

Molecule scenario validation

ansible/test-molecule owns the pinned runtime, bounded execution and report publication. Consumers own native inventory, playbook locations, resource lifecycle and test sequence. The action supplies no base configuration or VM dependency. __test-actions-ansible-test-molecule.yml tests a local scenario with custom playbook names, including native failure cleanup and bounded cleanup after timeout. The fixture creates only synthetic temporary files on the runner.

Its QEMU job additionally exercises deployment, idempotence, reboot and native failure reports against a VM created by the workflow. That scenario consumes SSH outputs and owns its reboot policy; the workflow always destroys the VM. Dependabot updates Molecule's requirements; validate both native and VM scenarios before accepting an update.

Native OpenTofu tests

opentofu/test composes the official setup Action with native init -backend=false and test. Consumers own module/test files, variable environment and disposable infrastructure. No formatting, provider setup, state bootstrap or arbitrary command is part of this action. Its dedicated workflow tests success, failed assertions, empty suites and initialization failure, including published artifacts.

OpenTofu currently has JSON test events but no JUnit output. The adjacent reporting adapter validates complete results and emits only filenames, run names and fixed outcome messages. It discards raw diagnostic/state content. Focused unit tests protect incomplete reports, escaping and cleanup failure after passing assertions. The upstream dflook test action was considered; its container does not expose the native events or a host runtime for the consumer's following recovery scenario. Reuse official setup and native execution, keeping only this reporting gap here.

Renovate maintains the fixture's .opentofu-version and the adapter's Node version; Dependabot maintains the upstream setup Action. Generate its reference with make docs.