Contributing
Where to ask for help with the open-source engine, how to report a bug or send a change, and the terms a contribution is accepted under, including the sign-off on every commit.
On this page
Engine This page is for anyone who wants help with the open-source parts of Sypnia, or wants to improve them: the engine and its Console, the SDKs, @sypnia/mcp, the agent skills and these docs. The Sypnia Cloud app is not open source and takes no contributions; for Sypnia Cloud, see Support.
Where things live
| What | Repository | Licence |
|---|---|---|
| The engine, the Console, the specifications, the deploy files | github.com/sypnia/sypnia | AGPL-3.0 |
| The agent skills | github.com/sypnia/skills | MIT |
The SDKs and @sypnia/mcp | Linked from each package’s page on npm | MIT |
| These docs | Linked from «Edit this page» at the bottom of every page, once it is public | CC BY 4.0 |
Ask a question, report a bug
Help for the open-source engine is given by the community, in the open, in the engine’s repository. We read it and answer when we can; there is no promised response time.
| You have | Where |
|---|---|
| A question about running or using the engine | The repository’s discussions |
| A bug | The repository’s issue tracker |
| An idea for a change | An issue, before any code |
| A security problem | Not in public. See Report a security problem. |
A bug report that gets fixed fast has:
- The version: the output of
sypnia version, and the SDK’s name and version. - The setup: the output of
sypnia doctor. It prints no secrets. - What you expected and what happened, one sentence each.
- How to repeat it. For a wrong number or a wrong grouping, the batch of events that shows it is the best report there is.
Never paste an API token or the root token. An ingest key is public and fine to share.
Send a change
Sypnia is built documentation-first, and a change follows the same order. The full flow, with the checks that run on every pull request, is in The codebase. In short:
Small fixes to the docs, such as a typo, a broken link or a clearer sentence, need no issue. Every page has an English and a Spanish version; change both, or say in the pull request that the other is missing, and someone will write it.
The terms of a contribution
They are short on purpose.
- Your contribution takes the licence of the repository it goes into: AGPL-3.0 for the engine and the Console, MIT for the SDKs,
@sypnia/mcpand the skills, CC BY 4.0 for the docs. What comes in is licensed exactly like what goes out. - You keep your copyright. You do not hand it to us.
- There is no contributor licence agreement to sign. Instead, every commit carries a sign-off.
The sign-off
The line Signed-off-by: Your Name <you@example.com> at the end of a commit message says that you agree to the Developer Certificate of Origin, version 1.1. In plain words, you state that:
- you wrote the change, or you have the right to submit it under the repository’s licence;
- if it builds on someone else’s work, that work’s licence allows it;
- you know the contribution is public and is kept, with your name and e-mail address, in the project’s history.
How to do it:
| To | Run |
|---|---|
| Sign a commit as you make it | git commit -s |
| Add the sign-off to your last commit | git commit --amend -s --no-edit |
| Add it to every commit of your branch | git rebase --signoff main |
Use your name, or the name you are known by, and an address that reaches you. A check on every pull request refuses commits without a sign-off.
What this means for you and for us
- Nobody, including us, can take your contribution and put it under another licence. The engine stays AGPL for everyone. Sypnia Cloud runs the engine as published.
- If your employer owns what you write, make sure you are allowed to contribute it. The sign-off is you saying that you are.
- Code written with the help of an AI tool is welcome on the same terms. You sign off on it like on any other change, so read it and make sure you may submit it.
- Code copied from elsewhere must come under a licence that fits the repository’s, and the pull request must say where it comes from.
What a maintainer looks for
Before style or taste, the rules of the engine: every new write can run twice safely, nothing takes a project as a bare string, no input can make the engine panic, and a migration only adds. They are explained, with the code, in The codebase.
Be specific and be kind. People read these threads in their spare time, in their second language.
Related
- The crates, the rules of the code, how to run it on your machine.
- What each licence lets you do.
- What is not built yet, and may be a good place to help.