Contributing to Raytha: issues, ideas and pull requests

Raytha is MIT-licensed and developed in the open at github.com/RaythaHQ/raytha. This page says where each kind of contribution goes and what makes it easy to act on. The repository's CONTRIBUTING.md is the authority; this page adds the practical detail.

Where things go

You want to	Go to
Ask how to do something	GitHub Discussions
Report a bug	GitHub issues
Suggest a feature or change	GitHub Discussions, in the Ideas category
Send code	A pull request against the `dev` branch
Get hands-on help with a project	Email [email protected] or see support and contact

Everyone taking part is expected to follow the project's Code of Conduct.

Report a bug

A report that can be reproduced gets fixed. The project asks for:

A description of the problem.
The steps to reproduce it.
The behavior you expected and the behavior you got.
Any error messages.
The Raytha version.
Screenshots, if they help.

Get the version from /healthz, which includes a version field (see Health checks), or from the VERSION file in your checkout. Error details are in the container logs: docker compose logs app.

A good report on a configuration problem also names the settings involved. Copy the variable names, not the values: never paste database passwords, SMTP passwords, API keys or webhook secrets into an issue.

Title: Health check reports unhealthy storage on a fresh install

Version: 2.0.0 (from /healthz)
Setup: docker compose, FILE_STORAGE_PROVIDER=Local, FILE_STORAGE_LOCAL_DIRECTORY set
Steps:
1. Start the stack and wait for the app to be up.
2. curl -i http://localhost:5001/healthz/ready
Expected: 200 with every check Healthy.
Actual: 503, storage check Unhealthy.
Logs: (paste the lines around the failure)

The example shows the shape of a report. It is not a known bug.

Suggest a feature

Start a thread in the Ideas category of GitHub Discussions before writing code for anything large. Describe the problem you have, not only the change you want, so others can suggest alternatives and the maintainers can judge fit.

Send a pull request

Fork the repository on GitHub.
Create a branch for your change.
Make the change, with tests. Local development explains how to run everything.
Run ./tools/ci-local.sh and fix what it reports.
Push to your fork and open a pull request against dev.

All contributions are accepted under the MIT license.

The repository's CI will check some things for you, so it is quicker to satisfy them first:

Version. VERSION must be bumped in the same change: PATCH normally, MINOR if you add an EF migration.
Admin bundle. If you changed anything in src/admin, rebuild and commit src/Raytha.Web/wwwroot/raytha.
SQL scripts. A new migration needs the matching files in db/Postgres.
Architecture rules. Tests in Raytha.Architecture.Tests fail a change that crosses a layer boundary or breaks a CQRS or authorization convention. See Architecture.

The engineering rules behind these checks are written down as numbered RFCs in the repository under .cursor/rules (rfc-0001-architecture.mdc through rfc-0013-admin-editors.mdc). They cover architecture, CQRS, data access, public Liquid rendering, the admin app, testing, security, webhooks and versioning, and they are plain Markdown.

Branches

main is production and is kept clean.
release-X.X.X is the next release branch. It takes bug fixes and security fixes, not new features.
dev is where features are developed. Pull requests go here.

When enough has landed in dev, a release-X.X.X branch is cut from it, merged into main and tagged. Work accepted into dev is typically slated for the next major release, so a small bug fix that should ship sooner is worth flagging in the pull request description.

Gotchas

Target dev, not main. main is the production branch.
Issues are for bugs. "How do I" questions belong in Discussions, where the answer can help the next person.
Do not post secrets, database dumps or real customer content in public threads. A database dump contains plaintext webhook secrets, SMTP passwords and JWT secrets (see Backups and restores).
To report a security problem, do not open a public issue. Email [email protected] with the details.

Next steps

Local development: run Raytha from source and run the tests.
Architecture: where a change belongs.
Introduction: back to the start.