Cover photo

Contributing to Aleo snarkOS: a step-by-step guide for developers

Hello, my name is Heorhii. In this guide, I’ll walk you through the process of contributing to snarkOS, the software powering Aleo’s blockchain infrastructure. We’ll look at how branches, networks, and contribution steps all tie together, ensuring your new features or fixes can be efficiently merged into the production environment. Whether you’re a newcomer or a seasoned contributor, this guide should help you navigate the workflow with clarity and confidence.

Quick overview: branches and networks

Branches:

  • staging branch. A staging ground for new changes. This is where code lands first to undergo testing and review before it’s elevated to the mainnet branch.

  • mainnet branch. The main production branch, containing stable, well-tested changes. Only merged from staging once everything is deemed production-ready.

Networks:

  • DevNet(s). Ideal for early testing of proposed changes. You can spin up local or specialized devnets to validate features before they move on.

  • CanaryNet (running staging branch). Used for broader testing and onboarding additional validators. Changes from DevNet migrate here for final checks before Testnet Beta or Mainnet.

  • Testnet Beta (running mainnet branch). A public test network emulating production. It’s used to test applications without real financial risks.

  • Mainnet (running mainnet branch). The final stage before a full release. It’s a stable environment that eventually becomes the canonical Mainnet.

Contribution workflow for snarkOS. Below is a step-by-step rundown of how to propose, develop, and merge new features into snarkOS.

1. Fork the Repository:

  1. Fork the snarkOS repository from the staging branch to your personal GitHub account.

  2. Clone your fork locally:

git clone git@github.com:<your-username>/snarkOS.git
cd snarkOS
git remote add upstream git@github.com:AleoNet/snarkOS.git

2. Switch to the base branch:

SnarkOS uses staging as the working branch where new changes land first:

git switch staging

3. Create a feature branch:

Create a branch for your specific feature or fix. This helps keep your work isolated and easy to review:

git checkout -b feat/my-branch

4. Develop and test your feature:

  1. Implement your changes. Write your code, implement the new feature or bug fix, and make sure it aligns with existing coding conventions.

  2. Run the Local DevNet:

    ./snarkOS/devnet.sh

    When prompted, choose to reinstall the snarkOS binary to ensure you’re testing against your local changes.

  3. Validate. Check that blocks progress normally, send some transactions, and confirm network stability for your feature or fix.

  4. Feature-specific tests. If your changes require specialized testing, run them now to catch issues early.

5. Commit and push:

  1. Commit your changes with a concise message:

    git add .
git commit -m "Add my awesome feature"

  2. Push to your fork:

    git push -u origin feat/my-branch

6. Submit a PR to your Fork’s main branch. Open a Pull Request (PR) from your feature branch to your fork’s main branch. This triggers any CI pipelines you have set up in your fork, running tests before it’s even seen by the main repository.

7. Internal code review. Your team (or you, if solo) can review the PR in your fork’s repository. Make sure all tests pass. If it meets your quality standards, merge it into your fork’s main branch.

8. Submit a PR to the main AleoNet/snarkOS Repository. Once your code is tested and approved internally:

  1. Open a PR from your fork’s main branch to the staging branch in AleoNet/snarkOS.

  2. Main CI PipelineThe official SnarkOS CI pipeline runs all relevant tests, ensuring your changes align with the project’s standards.

9. Review by Core team. Finally, core team members will review and approve or request changes. If everything passes:

  1. The PR merges into staging.

  2. Once thoroughly tested, it can later be merged into the mainnet branch for production.

More info is here:

https://developer.aleo.org/contribute/snarkos_contribute/

Wrapping up. Contributing to snarkOS involves a multi-step approach to ensure new features are robust, thoroughly tested, and ready for real-world usage. By working through staging first, code can pass through internal checks, devnet trials, and final reviews before ending up in the mainnet branch.

If you’re new to Aleo or SnarkOS, remember that each piece of code has the potential to impact a global, decentralized network. This structured workflow is designed to safeguard stability and security, so following it carefully is vital. Thank you for your interest in contributing to the Aleo community, and welcome aboard!

Happy coding!

To know more about Aleo, join now!

Prepared by Colliseum