Sipke Schoorstra f6d2d38536

test(user-tasks): add a persistence conformance suite with fault injection (#7986 )

Runs one suite unchanged against every implementation of IUserTaskRepository,
IUserTaskGuestSessionIssuer, and IUserTaskInvitationOutbox, plus a fault-injection
suite driving the real DefaultUserTaskManager and DefaultUserTaskInvitationService
against a real store. Gated providers report as skipped with a reason rather than
passing vacuously; ConformanceCoverageTests fails when a provider that must run is
unreachable or its variable is set but empty.

The suite found three defects, fixed here:

- VNextUserTaskRepository supplied no index values for WorkflowDefinitionId,
  WorkflowInstanceId, ActivityInstanceId, CreatedAt, or CompletedAt, all declared by
  its own schema provider, so every write through the VNext provider threw.
- The same provider resolved invitation token hashes by scanning on Status alone,
  which matched no declared index, so anonymous invitation verification always threw.
- EFCoreUserTaskInvitationOutbox persisted the delivery recipient but never read it
  back, so durably queued invitations reached the dispatcher with no address.

Also switches new ADRs to date-prefixed identifiers and generates doc/adr/toc.md via
scripts/adr/generate-toc.sh, with a --check mode and pull-request workflow so the
index is never hand-edited again.

2026-08-25 04:36:18 +02:00

4.8 KiB

Raw Blame History

Contributing to Elsa

Thank you for your interest in contributing to Elsa.

We value clarity, discipline, and maintainability in our codebase. Well-scoped pull requests and high-quality bug reports help us maintain velocity without sacrificing quality.

Whether you're:

Reporting a bug
Proposing a feature
Submitting a fix
Improving documentation
Becoming a maintainer

— your contributions are welcome.

Development Workflow

Elsa follows Trunk Based Development.

All changes happen through Pull Requests targeting the main branch.

Fork the repository and create your branch from main.
If you've added code that should be tested, add tests.
If you've changed APIs, update documentation.
Ensure the test suite passes.
Open a Pull Request.

Architecture Decision Records

Records live in doc/adr/. Name a new one YYYY-MM-DD-slug.md and give it a # heading with the title alone — no numeric prefix. The older NNNN- records stay as they are; do not renumber them, and do not continue the sequence. Sequential numbering had no reservation step, so two branches in flight always picked the same number and one of them had to be renumbered on merge.

doc/adr/toc.md is generated. After adding or retitling a record, run:

scripts/adr/generate-toc.sh

and commit the result. CI runs scripts/adr/generate-toc.sh --check and fails a pull request whose index is out of date, so the index is never hand-edited.

Pull Requests

We aim for PRs that are easy to review, easy to reason about, and safe to merge.

1) One PR = One Concern

Keep PRs focused on a single logical change:

✅ Bug fix
✅ Refactor (no behavior change)
✅ Formatting
✅ Dependency update
✅ Documentation change
❌ Mixing unrelated cleanups with functional changes

Why: Mixed concerns increase cognitive load, slow reviews, and increase merge risk.

If you notice cleanup opportunities while fixing a bug:

Prefer a follow-up PR titled refactor: ... or chore: ...
Or keep cleanup strictly limited to what is required for the fix

PRs that mix unrelated concerns may be asked to split before review continues.

2) Make Reviews Fast

A good PR includes:

A clear problem statement
Expected behavior
Steps to reproduce (if applicable)
Steps to verify the change
Screenshots or video for UI changes (if applicable)

The easier your PR is to review, the faster it can be merged.

3) Prefer Small PRs

Smaller PRs are:

Easier to review
Less risky to merge
More likely to receive timely feedback

If a change is large, consider splitting it into incremental PRs.

Reporting Bugs

We use GitHub Issues to track bugs and feature requests.

When reporting a bug, please include:

A clear summary
Steps to reproduce
Expected behavior
Actual behavior
Relevant logs or screenshots
Sample code (if applicable)

Thorough bug reports significantly increase the chance of a fast and accurate resolution.

Feature Requests & Prioritization

Elsa Workflows is an open source project, and as such, not all feature requests can be implemented immediately or on demand.

Feature development is prioritized based on a combination of the following factors:

1. Project Vision & Roadmap

Some features align closely with the long-term direction of Elsa and are prioritized accordingly.

2. Real-World Demand

Features that are backed by concrete use cases, especially in production environments, are more likely to be prioritized.

If a feature is important for your scenario, providing context about how you plan to use it is extremely helpful.

3. Community Contributions

Contributions from the community are strongly encouraged.

If you are able to propose a design or submit a pull request, it can significantly accelerate progress. Maintainers are happy to collaborate and review contributions.

4. Available Time & Maintainer Bandwidth

Elsa is actively maintained, but development capacity is limited. As a result, some features may take time to be implemented.

5. Sponsored / Paid Work

Organizations that require specific features or timelines can engage through commercial support.

This allows dedicated time to be allocated to specific work items and can accelerate development significantly.

What This Means in Practice

There are no guaranteed timelines for feature requests
Some features may remain open until one of the above factors changes
The best way to move a feature forward is to:
- Contribute a proposal or implementation
- Provide a strong real-world use case
- Sponsor or fund the work

We appreciate all feature requests and feedback — they help shape the direction of Elsa Workflows.

License

By contributing, you agree that your contributions will be licensed under the project's MIT License.

4.8 KiB Raw Blame History