Skip to content

Contributing

HybridOps is MIT-0 licensed where stated. Public contributions are welcome across the public documentation, runtime, workload, and Terraform module repositories.

Repositories

Repository Scope
hybridops-core Platform runtime, modules, drivers, blueprints, CLI
hybridops-workloads Kubernetes workload catalog (GitOps)
hybridops-terraform-gitmods Proxmox VM and LXC Terraform modules
terraform-proxmox-sdn Proxmox SDN Terraform module

The hybridops.* Ansible collections are distributed through Ansible Galaxy. Use the Galaxy Collections reference for install paths, versions, and role scope.

What to contribute

Good contributions include:

  • Bug fixes with a clear reproduction path
  • New modules, roles, or blueprints following the existing contract structure
  • Test coverage improvements (smoke tests, Molecule scenarios, integration probes)
  • Documentation improvements (corrections, examples, missing context)
  • HOWTO guides for real operational tasks you have performed

Before opening a large PR, file an issue or discussion first to align on scope and approach.

Workflow

  1. Fork the repository and create a feature branch.
  2. Make changes. Keep commits focused; prefer small, reviewable PRs.
  3. For modules and roles: run smoke tests locally before pushing.
  4. For Terraform modules: run terraform fmt and terraform validate.
  5. Open a pull request with a clear description, what you changed, and why.
  6. Link any relevant issues, ADRs, or HOWTOs.

Standards

Modules and roles

  • Roles must be idempotent and free of hardcoded secrets, IPs, or hostnames.
  • Modules must declare inputs, guards, and evidence expectations in spec.yml.
  • Avoid logging sensitive values in task output or evidence artefacts.

Ansible collections

  • Each role provides roles/<role_name>/tests/smoke.yml and tests/inventory.example.ini.
  • Molecule scenarios are recommended for multi-node or container-orchestration behaviour.
  • Public collection consumption is through Ansible Galaxy; maintainer source work happens through the project release workflow.

Terraform modules

  • All variables must have descriptions. Sensitive variables must use sensitive = true.
  • Modules should be idempotent and include a working example under examples/.

Documentation

  • New modules and roles should have a corresponding HOWTO or runbook entry.
  • ADRs document significant decisions: use the template when making architectural choices.
  • Documentation is CC BY 4.0; keep it accurate and testable.

Security

Do not commit secrets, tokens, client IDs, or passwords. If you discover a security issue, report it privately through the security contact for the relevant public repository or the HybridOps contact channel.

License

By contributing, you agree that your contributions will be licensed under the same license as the repository you are contributing to (MIT-0 for code, CC BY 4.0 for documentation). See Licensing for details.