Docs

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.

Applies to Engine At launch

View as Markdown
On this page
  1. Where things live
  2. Ask a question, report a bug
  3. Send a change
  4. Open an issue first
  5. Change the docs before the code
  6. Write the code with its tests, and sign your commits
  7. Open the pull request
  8. The terms of a contribution
  9. The sign-off
  10. What this means for you and for us
  11. What a maintainer looks for
  12. Related

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

WhatRepositoryLicence
The engine, the Console, the specifications, the deploy filesgithub.com/sypnia/sypniaAGPL-3.0
The agent skillsgithub.com/sypnia/skillsMIT
The SDKs and @sypnia/mcpLinked from each package’s page on npmMIT
These docsLinked from «Edit this page» at the bottom of every page, once it is publicCC 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 haveWhere
A question about running or using the engineThe repository’s discussions
A bugThe repository’s issue tracker
An idea for a changeAn issue, before any code
A security problemNot in public. See Report a security problem.

A bug report that gets fixed fast has:

  1. The version: the output of sypnia version, and the SDK’s name and version.
  2. The setup: the output of sypnia doctor. It prints no secrets.
  3. What you expected and what happened, one sentence each.
  4. 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:

  1. Open an issue first

    Say what should change and why. It saves you from writing something that cannot be merged. Some changes are decisions, not code, and are settled in an issue: a new required service, a change that would split existing problems, an integration that sends alerts to a chat product.

  2. Change the docs before the code

    If behaviour changes, the page that describes it changes in the same pull request, and so does the file in spec/ when an endpoint, an event, a setting or a command moves. A behaviour change without its docs change is not reviewed.

  3. Write the code with its tests, and sign your commits

    Terminal
    git commit -s -m "Fix the p75 of an hour with no views"
    You should see

    The commit message ends with your sign-off:

    Text
    Fix the p75 of an hour with no views
    
    Signed-off-by: Ana Ruiz <ana@example.com>
  4. Open the pull request

    The automatic checks must pass. A maintainer reviews, may ask for changes, and merges.

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/mcp and 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:

  1. you wrote the change, or you have the right to submit it under the repository’s licence;
  2. if it builds on someone else’s work, that work’s licence allows it;
  3. 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:

ToRun
Sign a commit as you make itgit commit -s
Add the sign-off to your last commitgit commit --amend -s --no-edit
Add it to every commit of your branchgit 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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close