Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
126 lines (82 loc) · 3.08 KB

CONTRIBUTING.md

File metadata and controls

126 lines (82 loc) · 3.08 KB

Contributing to Zigflow

Thanks for your interest in Zigflow.

Zigflow is a community-maintained DSL for Temporal. It aims to be stable, predictable and production-ready. Contributions are welcome, but changes should align with the long-term design goals of the project.

If you are planning a significant change, please open an issue first to discuss it before submitting a pull request.

Naming

The project name is Zigflow.

Use this exact capitalisation in documentation, comments and user-facing text.

Lowercase zigflow is only acceptable in CLI commands, package names or URLs.

Getting started

The recommended development environment is a Dev Container. Opening the repository in a Dev Container provides a fully configured environment.

Before submitting a pull request:

  • Ensure the project builds successfully
  • Ensure all tests pass
  • Add or update tests where behaviour changes
  • Update documentation if needed

Development principles

Zigflow aims to:

  • Provide a clear and expressive DSL for Temporal workflows
  • Maintain backwards compatibility wherever possible
  • Avoid unnecessary abstraction or complexity
  • Prefer explicit behaviour over implicit magic

Breaking changes should be rare and must be discussed in advance.

Specification compatibility

Zigflow is influenced by and aims to remain broadly compatible with the ServerlessWorkflow.io specification.

Where possible, new features and behavioural changes should align with the Serverless Workflow specification to minimise conceptual friction and improve interoperability.

However, Zigflow is designed specifically for Temporal. In cases where the Serverless Workflow specification does not map cleanly to Temporal's execution model, determinism requirements or workflow semantics, Zigflow may diverge.

When proposing changes that affect compatibility:

  • Clearly explain how the proposal relates to the Serverless Workflow specification
  • Identify any areas of divergence
  • Justify deviations based on Temporal's design constraints

Compatibility is a goal, but not at the expense of correctness, determinism or clarity within Temporal.

How to contribute

  1. Fork the repository
  2. Create a feature branch
  3. Make focused, well-scoped changes
  4. Add or update tests
  5. Open a pull request with a clear description of the change and its motivation

Pull requests that introduce new features should explain:

  • The problem being solved
  • Why this approach was chosen
  • How it impacts existing users

Large architectural changes without prior discussion may not be accepted.

Commit style

All commits must follow the Conventional Commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common types include:

  • feat
  • fix
  • docs
  • refactor
  • test
  • chore

Use ! for breaking changes and document them clearly.

Code of conduct

Please read and follow our Code of Conduct.