Contributing

There are many ways to contribute to Ideal: reporting bugs, suggesting features, improving documentation, and submitting patches. No contribution is too small.

See Communication Channels for all addresses and interaction methods.

Reporting Issues

Browse existing tickets at todo.sr.ht/~cpradog/ideal before filing a new one to avoid duplicates.

To file an issue, either open a ticket on the tracker or send a plain-text email to ~cpradog/ideal@todo.sr.ht.

The tracker is shared across all Ideal repositories. Use a prefix in the subject line to identify the affected repository, for example [ideal-docs] or [ideal-core].

When reporting a bug, include:

• A clear description of the problem.
• Steps to reproduce it.
• What you expected to happen and what actually happened.
• Relevant version or commit information.

Reporting Security Vulnerabilities

Do not use the public issue tracker for security issues. Instead, send a plain-text email to the write-only ideal-security list at ~cpradog/ideal-security@lists.sr.ht. The archive is not publicly visible — only maintainers can read reports.

Include the same information as a regular bug report, plus an assessment of the potential impact if known.

Submitting Patches

Ideal uses a patch-based workflow via git-send-email. Patches are sent to the ideal-devel mailing list for review and discussion.

Setup

Follow the installation and configuration steps at git-send-email.io, then configure the target repository once:

git config sendemail.to "~cpradog/ideal-devel@lists.sr.ht"
git config format.subjectPrefix "PATCH <repository>"

Replace <repository> with the repository name (e.g., ideal-docs, ideal-core).

note

The subject prefix must match the repository name so that hub.sr.ht can associate the patch with the correct repository. This is how patches are organized and tracked per module — without the right prefix, your patch will not appear linked to the repository it targets.

Sending a Patch

Make your changes in one or more commits, then send them for review:

git send-email --base=HEAD~1 --annotate -1 -v1

For a series of multiple commits:

git send-email --base=origin/main --annotate -v1 origin/main..HEAD

The --annotate flag opens each message in your editor before sending. Use the area below the --- line to add notes for reviewers — this text appears in the email but is not part of the commit.

Your patch will appear in the patches queue for review.

Guidelines

• Keep patches focused — one logical change per patch.

• Write clear commit messages: a short summary line, a blank line, then a longer explanation if needed.

• Make sure the project builds and passes any existing checks before submitting.

• If a patch addresses a tracked issue, use a trailer to link it:

  Fixes: https://todo.sr.ht/~cpradog/ideal/123

  Supported trailers: Fixes, Closes, Implements, References. When pushed, hub.sr.ht will automatically update the linked ticket (the pusher must have triage access to the tracker).

Revisions

If changes are requested during review, send a revised version:

git send-email --base=HEAD~1 --annotate -1 -v2

Increment the version number (-v2, -v3, ...) with each revision. Use the area below the --- line to describe what changed since the previous version.

warning

Do not use --in-reply-to to thread a revised patch under the original. This merges both versions in the SourceHut patches UI, making them harder to track. Send each revision as a new top-level thread instead.

Review Process

Reviewers provide feedback by replying inline to patch emails. A patch progresses through these statuses:

Status	Meaning
Proposed	Awaiting review (initial state).
Needs revision	Changes requested — send a new version.
Superseded	Replaced by a newer version.
Approved	Accepted, pending merge.
Applied	Merged into the repository.
Rejected	Not accepted.

You can check the current status of your patches in the patches queue.