Contributing #
Contributions to FluentCI Modules should keep modules reusable, independently buildable, and documented. Read the target module's README and source before making changes.
Set up a module #
Install Node.js, Bun, Spago, and the PureScript compiler. Initialize the native
component toolchain with bun install --cwd lib/component --frozen-lockfile. Run commands
from the module directory; there is no root npm workspace:
cd publishing/gemfury
npm ci
npm run build
npm test
Build before testing because tests load compiled PureScript or a bundled
plugin. Each build produces dist/plugin.wasm. Buildx additionally requires
Python 3. Its generated input schema and Cachix support code are included in
the checkout.
Module conventions #
- Place modules under the appropriate category, such as
packaging/,containers/,caching/, orpublishing/. - Write module behavior in PureScript and expose WebAssembly entry points
through explicit typed functions in
src/CI/Component.pursandentry.mjs. Give every argument a source description and return a native typed value. - Include a README, MIT
LICENSE, package manifests and lockfiles, Spago configuration and lockfile, build script, tests, and.gitignore. - Register new modules in the root
fluentci.tomlwith a unique name, version, source path,sdk = "purescript", andruntime = "component". Update the root README's module table as well. - Keep module metadata, paths, payloads, and configuration generic. Avoid embedding a particular application's binary name or release layout.
- Validate configuration before changing files or publishing artifacts. Check host OS restrictions and required external tools where applicable.
- Pass external commands as literal argument arrays through the FluentCI host API. Keep credentials in environment variables or secret stores, rather than interpolating their values into commands or logs.
- Document entry points, input types, required tools, environment variables, output paths, platform restrictions, and failure behavior.
Keep generated build output and installed dependencies out of Git, including
dist/, output/, .spago/, and node_modules/. Never commit credentials or
local environment files such as .envrc.
The setup modules share the checked-in lib/setup package and the fixtures
in test/setup. Rebuild every setup module after changing that shared library,
then run their tests. See the setup guide for OS coverage
and optional upstream smoke tests. Keep new module registrations alphabetized
by name in fluentci.toml.
The cloud, code-quality, container, deployment, formatting, infrastructure,
linting, secrets, security, testing, and Python/Nix package modules share lib/cli and test/cli. Edit lib/cli/catalog.json, run
escript scripts/fluentci_modules_ci generate-cli, and rebuild and test all affected CLI
modules. CI checks generated entry points, argument references, and schemas.
Tool installers are described in lib/setup/tools.json; regenerate with
escript scripts/fluentci_modules_ci generate-setup. Every setup registration uses the
setup- prefix. Run escript scripts/fluentci_modules_ci audit-modules after adding exports; the
export audit records their pipeline role.
Verification #
Run the affected module's build and tests. Add tests for meaningful changes to behavior, including validation failures and native command failures. Stub-host tests should exercise compiled code and avoid real credentials, uploads, or package installation.
The dpkg and rpmbuild modules are Linux-only. Their native integration tests run when the required packaging tools are installed and otherwise skip. For packaging changes, run those tests on Linux and confirm they actually execute, then inspect the generated package metadata and payload. Selecting a target architecture does not provide a cross-compiler.
For Buildx, edit buildx-options.json and regenerate using escript ../../scripts/fluentci_modules_ci generate-buildx
rather than editing generated command sources or OPTIONS.md directly.
escript ../../scripts/fluentci_modules_ci generate-buildx --check checks generated files without rewriting them.
Run escript scripts/fluentci_modules_ci generate-components after updating the source catalogs.
Keep explicit typed argument records, native return types, and source @param
descriptions for every public function. See components.
Run escript scripts/fluentci_modules_ci validate-modules after changing module metadata or
registration. CI derives its Linux/macOS matrix from this registry and validates
compiled guest exports; see the CI guide.
Before submitting, check for whitespace errors:
git diff --check
For documentation-only changes, verify examples against the source and check local links. Include any skipped checks and the reason in your pull request.
Commits and pull requests #
Use focused conventional commits, for example:
feat(dpkg): support an additional architecture alias
fix(gemfury): preserve literal package filenames
docs: document module setup
chore(modules): register a new module
Keep unrelated changes in separate commits. Pull requests should explain the problem, resulting behavior, and validation performed. Describe any changes to entry points, configuration, or supported platforms so users can migrate.
License #
Contributions are made under the repository's MIT License. Keep module license files and package license metadata consistent with it.
BEAM repository helpers #
Automation commands are implemented in Gleam under scripts/src. Compile with
cd scripts && gleam build --target erlang --warnings-as-errors && gleam export escript.
Use escript scripts/fluentci_modules_ci generate-all after changing reviewed
catalogs or declarative contract templates, and check-all for drift checks.
Helper regression coverage is in scripts/test; CI uses published setup-erlang
and setup-gleam before compilation. Respect AGENTS.md before running local builds
or tests. See scripts/README.md for the full command list.