A collection of +180 reusable WebAssembly modules for building composable CI/CD pipelines with FluentCI fluentci.io/modules
modules CONTRIBUTING.md
6.3 kB · 128 lines
Markdown
at main

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/, or publishing/.
  • Write module behavior in PureScript and expose WebAssembly entry points through explicit typed functions in src/CI/Component.purs and entry.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.toml with a unique name, version, source path, sdk = "purescript", and runtime = "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.