1  # Contributing to Apibara
  2  
  3  First off, thank you for contributing to Apibara ❤️! Apibara is built by
  4  developers passionate about open-source like you.
  5  
  6  This guide will go through the recommended workflow for new contributors.
  7  
  8  ## Before you start
  9  
 10  The first step is to decide what to work on. The best place to look for work is
 11  the [project's issues](https://github.com/apibara/dna/issues). Issues labelled
 12  "Good first issue" are small tasks that don't require specialized knowledge of
 13  the Apibara codebase.
 14  
 15  If you're an Apibara user, you can also propose changes to Apibara that solve
 16  your pain points. In this case, please open an issue before starting to work.
 17  
 18  After you decide what to work on, hop on the
 19  [Discord server](https://discord.gg/VDh2CRQ4) to chat with our team. The
 20  `#open-source` channel is perfect for syncing and receiving early feedback on
 21  your contribution.
 22  
 23  ## Development
 24  
 25  Apibara DNA is built in Rust. We use [Nix](https://nixos.org/) to create
 26  reproducible builds. While Nix is terrific, we understand it's also a complex
 27  tool, and this section will help you start with it. For an easier setup, you can
 28  **use the provided devcontainer** that installs and configures Nix for you.
 29  
 30  **Installing Nix**
 31  
 32  If you don't have Nix installed, install it on your system. The
 33  ["Zero to Nix"](https://zero-to-nix.com/start/install) guide has a great
 34  tutorial on it.
 35  
 36  **Clone the project**
 37  
 38  Clone the project using git:
 39  
 40  ```
 41  git clone git@github.com:apibara/dna.git
 42  # or
 43  git clone https://github.com/apibara/dna.git
 44  # or
 45  gh repo clone apibara/dna
 46  ```
 47  
 48  **Setting up the development environment**
 49  
 50  We use Nix to create the development environment will all the required
 51  dependencies. From the project root, run:
 52  
 53  ```
 54  nix develop
 55  ```
 56  
 57  You will then be in a bash shell with the correct Cargo, rust version, and all
 58  the required external libraries and tools (like the `protoc` compiler).
 59  
 60  **Building & Testing**
 61  
 62  You can use all the standard cargo commands for development. Before submitting
 63  your PR, ensure all the projects build with Nix. For example:
 64  
 65  ```
 66  nix build .#apibara-starknet
 67  ```
 68  
 69  **Committing changes**
 70  
 71  This project prefixes changes with the subproject it changed and then a short
 72  commit message. Usually, we prefer a single commit for each unit of work, so use
 73  `git commit --amend` freely while developing.\
 74  If the commit is large, please briefly describe why you made this change.
 75  
 76  ```
 77  starknet: change X to Y
 78  
 79  This change is needed because ...
 80  ```
 81  
 82  Don't use any prefix if your change concerns CI or the build system.
 83  
 84  We recommend splitting significant contributions up into many independent
 85  stacked changes. Our team recommends using
 86  [Graphite for stacked changes](https://graphite.dev/).
 87  
 88  ## Code Review
 89  
 90  Open a Pull Request on GitHub when you think your contribution is ready for
 91  review, and we will review it as soon as possible.
 92  
 93  The review process helps us keep the project's code quality high, so expect to
 94  receive comments and suggestions on improving the code.
 95  
 96  **Updating your Pull Request**
 97  
 98  After updating the code with your changes, amend the previous commit:
 99  
100  ```
101  git commit --amend
102  # or with graphite
103  gt commit amend # gt ca also works
104  ```
105  
106  This step ensures that git history always looks clean and tidy. Push changes to
107  your fork:
108  
109  ```
110  git push --force-with-lease
111  ```
112  
113  After your PR is in good shape, we will merge it into the main branch and ship
114  it. Congratulations, the code you wrote is now used by hundreds of developers
115  and thousands of end users 🎊
116  
117  ## Making a release
118  
119  Releases are prepared manually to ensure changes are communicated effectively.
120  
121  **1. Update crate version**
122  
123  Update crate version, following
124  [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
125  
126  **2. Update changelog**
127  
128  Update the `CHANGELOG.md` file in the target crate, following
129  [Common Changelog](https://common-changelog.org/). Make sure to include the link
130  to the release that will be created in Step 5.
131  
132  **3. Open a Pull Request**
133  
134  Open a Pull Request with the release changes.
135  
136  **4. Merge & wait for CI**
137  
138  Nothing much to do here.
139  
140  **5. Create GitHub Release**
141  
142  Create a release on GitHub, creating a new tag in the format
143  `<crate>/v<version>` (e.g. `operator/v1.2.3`).