Skip to content

Latest commit

 

History

History
203 lines (138 loc) · 6.29 KB

CONTRIBUTING.md

File metadata and controls

203 lines (138 loc) · 6.29 KB
Raw

How to Contribute

Welcome to the Resonate project! We appreciate your interest in helping us build reliable and scalable distributed systems. To get started, follow these simple steps:

Initial setup

We follow the fork and branch workflow. There will be three Git repositories involved:

  1. upstream - the resonate repository on GitHub.
  2. origin - your GitHub fork of upstream.
  3. local - your local clone of origin.

These steps are only needed once and not for subsequent changes you might want to make:

  1. Fork the resonate repository on GitHub to create origin. Visit resonate GitHub repository and click the Fork button.

  2. Make a local clone of your fork.

    git clone [email protected]:<your-user-name>/resonate.git

  3. Add a remote pointing from local to upstream.

    cd resonate
git remote add upstream [email protected]:resonatehq/resonate.git

  4. Double check the two remotes are referencing the expected url.

    git remote get-url origin   # [email protected]:<your-user-name>/resonate.git
git remote get-url upstream # [email protected]:resonatehq/resonate.git

Development workflow

Here is a outline of the steps needed to make changes to the resonate project.

  1. Make a local branch in your clone and pull any recent changes into it.

    git switch -c awesome_branch  
git pull upstream main

  2. Make changes and commit to local branch.

    git add .
git commit -m "dead simple"

  3. Pull any changes that may have been made in the upstream repository main branch.

    git pull --rebase upstream main # may result in merge conflicts

  4. Push your branch to the corresponding branch in your fork.

    git push origin awesome_branch

  5. Select the branch you are working on in the drop-down menu of branches in your fork. Then hit the Compare and pull request button.

  6. Once your pull request has been reviewed and approved by a maintainer, select the Squash and merge option. Edit the commit message as appropriate for the squashed commit.

  7. Delete the branch from origin:

    git push origin --delete awesome_branch

  8. Delete the branch from local:

    git switch main
git branch -D awesome_branch

Working with Nix

This repo currently has some optional Nix stuff that you can experiment with.

Getting started

To get started, install Nix on either Linux or macOS (the install script infers which system you're on):

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

This could take a few minutes. If you need to cleanly uninstall Nix and all of its system dependencies at any time:

/nix/nix-installer uninstall

The development environment

Once Nix is on your system, you can activate the Nix development environment in this repo:

nix develop

With that command, you enter a project-specific shell with pinned packages for all of the tools required for the project (Go 1.21, protoc plus plugins, etc.). All the make commands in the Makefile, for example, should just work inside the shell.

In order to streamline activating the development shell, it's recommended to install direnv. If you install direnv and run direnv allow in this repo, the Nix development shell will be activated automatically every time you cd into the repo, which makes explicitly running nix develop unnecessary. If you'd like to disable direnv in this repo, you can run direnv revoke.

Optionally, you can install nix-direnv in addition to direnv. nix-direnv provides a faster implementation of direnv's Nix functionality (though direnv should work just fine in this repo without it).

Building the server as a package

In addition to the development environment, you can build the Resonate server as a Nix package:

nix build

When that succeeds, the binary will be available at ./result/bin/resonate:

./result/bin/resonate serve

result is actually a symlink to a Nix store path:

realpath result
/nix/store/xmjcz2rm3l8k8wjnvm4yk7m8fkp59apj-resonate-0.5.0 # the hash will differ on your system

In order to handle Go dependencies, this project uses a tool called gomod2nix. What this tool essentially does is inspect go.mod and generate a gomod2nix.toml file that Nix can use to generate derivations for each Go dependency.

Whenever you update the go.mod file, you need to run gomod2nix (included in the Nix development environment) to regenerate gomod2nix.toml. If you update go.mod but forget to regenerate gomod2nix.toml, the Ensure gomod2nix dependencies are up to date job will fail in CI.

Running the server directly using Nix

As an alternative, you can run the server directly using Nix:

nix run

# To pass in args
nix run . -- serve

Building the Docker image with Nix

For x64 Linux users, you can even build the Resonate Docker image using Nix (with no dependence on the Dockerfile or the Docker CLI):

nix build .#dockerImages.x86_64-linux.default

To load the image:

docker load < result

What to contribute to?

Here are some areas where your contributions would be valuable:

  • Bug fixes for existing packages.
  • Refactoring efforts to improve code quality.
  • Enhancements to our testing and reliability efforts.
  • Add support for the following databases: MySQL, Elasticsearch, MongoDB.

Thank you for your contributions and support in building a better Resonate! 🚀