Contributing to Synapse

Thank you for helping to improve the project! We are so happy that you are contributing! 💖

You can contribute to the project at any level. Whether you are new to web development or have been at it for ages doesn't matter. We can use your help!

No contribution is too small, and all contributions are valued.

This guide will help you to get started. It includes many details, but don't let that turn you away. Consider this a map to help you navigate the process, and please reach out to us with any questions and concerns in the our public channel .

Conduct

Please review our Code of Conduct which describes the behavior we expect from all contributors. Please be kind, inclusive, and considerate when interacting with contributors and maintainers.

Contributing in issues

You can contribute by opening an issue to request a feature or report a bug. We also welcome comments on an issue, bug reproductions, and pull requests if you see how to address an issue.

If you are still determining the details of a feature request, you can start with a discussion where we can informally discuss what you have on your mind.

Anyone can participate in any stage of contribution. We urge you to join in the discussion around bugs and comment on pull requests.

Asking for help

If you have reviewed our documentation and still have questions or are having problems, ask for help in the our public channel or start a discussion.

Submitting a bug report

We provide a template to give you a starting point when submitting a bug report. Please fill this template in with all relevant information, but feel free to delete any sections that do not apply.

The most important information is describing the problem and how it impacts you. We also invite you to propose a solution, which could be a description of expected behavior.

We very much appreciate it if you could include a short, self-contained, correct example that demonstrates the issue.

Development

If you have been assigned to fix an issue or develop a new feature, please follow these steps to get started:

• Fork this repository.
• Install dependencies by running pnpm install.
  • We use pnpm for package management.
  • Make sure you have Node LTS installed in your system.
• Optionally run npx simple-git-hooks to install git hooks for linting and formatting.
  • Current configuration run biome on staged files.
• Implement your changes to files in the src/ directory and corresponding test files in the /test directory.
• Git stage your required changes and commit (see below commit guidelines).
• Submit PR for review

If using an AI tool, you are welcome to load AGENTS.md into your context to teach it about the structure and conventions of this SDK.

Repo structure

- packages/
  - synapse-sdk/ SDK
  - synapse-core/ Core 
  - synapse-react/ React hooks
- examples/ Usage examples and starter kits
- apps/ Apps using Synapse
- docs/ This documentation site
- package.json Root package file

Generating ABIs

pnpm run generate-abi # in the synapse-core package

Wireit

This repo use wireit to run scripts, enable incremental build, setup dependencies between workspaces and cache results.

To run a script without cache prepend WIREIT_CACHE=none to the script like WIREIT_CACHE=none pnpm run build.

To run a script in watch mode append --watch.

To pass extra arguments to the script use pnpm run {script} {npm args} {wireit args} -- {script args}

Codespaces

This repo has a dev container configuration to enable one click setup of a development environment using Codespaces.

Pull requests

Pull requests are how we make changes.

Even tiny pull requests to fix typos or improve comments are welcome. Before submitting a significant PR, it is usually best to start by opening an issue or starting a discussion. Taking one of these steps increases the likelihood that your PR will be merged.

All commits must be signed before a pull request will be accepted. See the GitHub signing commits and telling git about your signing key documentation. We recommend generating a new SSH key for signing if you are setting up signing for the first time.

We squash and merge all PRs. Orderly, well-written commits will help us during review, but we don't require a pristine commit history.

Tests

If your change alters existing code, please run the test suites:

pnpm run lint

pnpm run test

# Node.js only tests 
pnpm test:node # add --watch for watch mode

# Browser only tests
pnpm test:browser # add --watch for watch mode

If you are adding a new feature, please add tests that prove the code works correctly and reference them when you submit the pull request.

Discuss and update

You will likely receive feedback or requests for changes to your pull request. Don't be discouraged! Pull request reviews help us all to collaborate and produce better code. Some reviewers may sign off immediately, and others may have more detailed comments and feedback. It's all part of the process of evaluating whether the changes are correct and necessary.

Once the PR is open, do not rebase the commits. Add more commits to address feedback. We will squash and merge all contributions, and we may clean up the history recorded in the final commit.

Merging

The primary goals for a pull request are to improve the codebase and for the contributor to succeed. Some pull requests may not be merged at the end of the day, but that does not indicate failure. If your pull request is not merged, please know that your efforts are appreciated and will have an impact on how we think about the codebase in the long run.

Release Process

Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for our packages. Release Please does so by parsing your git history, looking for Conventional Commit messages, and creating release PRs.

What's a Release PR?

Rather than continuously releasing what's landed to our default branch, release-please maintains Release PRs:

These Release PRs are kept up-to-date as additional work is merged. When we're ready to tag a release, we simply merge the release PR.

When the release PR is merged the release job is triggered to create a new tag, a new github release and run other package specific jobs.

How to merge the Release PRs?

Overview:

• Release PRs are created individually for each package in the mono repo.
• The merge order matters. We start with synapse-core, then synapse-sdk, then synapse-react.
• Only merge ONE release PR at a time and wait for release-please CI to finish before merging another.
• Dependent packages like synapse-core and synapse-sdk will have to resolve conflicts before merging because the main branch will have an updated synapse-core version. Conflicts should be handled by "accepting incoming changes" and then manually again updating the version for the package that is about to be released (e.g., synapse-sdk, synapse-react). This effectively updates the dependencies in the "Release PR" branch. (Example merge commit.)

Below are the specific steps to take. They use the example of releasing synapse-core=0.1.1, synapse-sdk=0.35.2, and synapse-react=0.1.1.

#	Package	Step	Example
1	synapse-core	Find the synapse-core PR	example
2	synapse-core	Squash and merge the PR	example
3	synapse-core	Ensure the release-please workflow completes	example
4	synapse-sdk	Find the synapse-sdk PR	example
5	synapse-sdk	Resolve conflicts by accepting incoming changes and then resetting the synapse-sdk version	example
6	synapse-sdk	Squash and merge the PR	example
7	synapse-sdk	Ensure the release-please workflow completes	example
8	synapse-react	Find the synapse-react PR	example
9	synapse-react	Resolve conflicts by accepting incoming changes and then resetting the synapse-sdk version	example
10	synapse-react	Squash and merge the PR	example
11	synapse-react	Ensure the release-please workflow completes	example

How should I write my commits?

Release Please assumes you are using Conventional Commit messages.

The most important prefixes you should have in mind are:

• fix:, chore:, test: and docs: correlates to a semver patch.
• feat: which represents a new feature, and correlates to a semver minor.
• feat!:,fix!:, chore!:, etc. or BREAKING CHANGE in the footer, which represent a breaking change (indicated by the !) and will result in a semver major.

Examples

# Patch releases (0.x.Y)
git commit -m "fix(payments): resolve approval race condition"
git commit -m "docs: update storage service examples"
git commit -m "test: add unit tests for PieceCID calculation"
git commit -m "chore: update dependencies"

# Minor releases (0.X.y)
git commit -m "feat: add CDN support for downloads"
git commit -m "feat(storage): implement batch upload operations"

# Major releases (X.y.z) - AVOID UNTIL M1
git commit -m "feat!: remove deprecated payment methods"
git commit -m "fix: update API signature

BREAKING CHANGE: The createStorage method now requires explicit provider selection"