Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (137 loc) · 13.4 KB

CONTRIBUTING.md

File metadata and controls

199 lines (137 loc) · 13.4 KB
Raw

Contributing to SV2 Applications

First off, thanks for taking the time to contribute! ❤️

All types of contributions are encouraged and valued. See the Table of Contents for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉

And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:

  • Star the project
  • Tweet about it
  • Refer this project in your project's readme
  • Mention the project at local meetups and tell your friends/colleagues

Table of Contents

I Have a Question

If you want to ask a question, we assume that you have read the documentation available at stratumprotocol.org/docs.

Best way to ask a question is to hop onto our community Discord. Two most suitable places to post a question are:

  • #newbies-qs and
  • #dev, for technical questions, suitable for developers building on top of SRI, or contributing to it.

If you then still feel the need to ask a question and need clarification, we recommend the following:

  • Open an Issue.
  • Provide as much context as you can about what you're running into.

We will then take care of the issue as soon as possible.

What Should I Know Before I Get Started

Important Resources About SV2 Applications

In order to have a better overview about what SV2 Applications covers, have a look at the following resources before getting started with contributions.

  • Stratum V2 Protocol Specifications.
    • Studying SV2 specs can take some time and requires effort, but it's the best way to properly understand what SV2 is about and how it's composed.
  • SRI Getting-started guide.
    • This can be explored in the meantime of SV2 protocol study, so that it can help getting a general overview about SV2. Moreover, it's the best way to really understand how the broader SRI project is built on.
  • Main SRI Repository.
    • This is the core Stratum V2 Reference Implementation containing the protocol libraries and primitives that these applications depend on.
  • Stratum V2 Master Degree Thesis (by @gitgab19).
    • This resource can be useful to get some knowledge about Bitcoin mining, pooled mining protocols history, and Stratum V2.
  • Stratum V2 Explained - Videos Playlist (by @plebhash).
    • This is a series of videos explaining Stratum V2 in depth, which cover the aforementioned topics.

Project Communications

Most project communications happen in our Discord server. Communications related to general development typically happen under dev channel.

Discussion about specific codebase work happens in GitHub issues and on pull requests. For protocol-level discussions, see the main SRI repository.

Our dev calls are scheduled every Tuesday at 16:00 UTC. You can see them in the sidebar under Events on Discord and subscribe to them to be notified.

I Want To Contribute

When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.

Project Structure

This repository is part of the broader SRI ecosystem. You can contribute to different aspects of Stratum V2:

  • SV2 Applications (this repository)
    • This repo contains production-ready pool and miner applications built on top of SRI, organized in workspaces:
      • pool-apps/ - Pool server and Job Declarator Server for pool operators
      • miner-apps/ - Job Declarator Client, Translator Proxy, and test utilities for miners
      • integration-tests/ - End-to-end testing suite
  • Stratum V2 Reference Implementation
    • This repo contains the core SV2 protocol implementation, libraries, and primitives written in Rust.
  • Stratum V2 Specifications
    • This repo contains the entire SV2 protocol specifications.
  • SRI website - stratumprotocol.org
    • This repo manages our website, containing docs, specs, and getting-started guides.

Contribution workflow

The SRI project follows an open contributor model, where anyone is welcome to contribute through reviews, documentation, testing, and patches. Follow these steps to contribute:

  1. Fork the Repository

  2. Create a Branch

  3. Make Your Changes

    These guidelines should be kept in mind:

    • When touching Rust code, make sure the changes have corresponding Rustdocs. Be concise and avoid unnecessary verbosity.
    • When adding or modifying features, check whether some corresponding documentation on .md files needs to be updated accordingly.
    • Make sure to run ./scripts/build-all-workspaces.sh (builds all workspaces: pool-apps, miner-apps, integration-tests) and ./scripts/clippy-fmt-and-test.sh (runs clippy, tests and formatting across all workspaces) on your changes. The equivalent cargo build, cargo test, cargo clippy and cargo fmt commands can also be run individually in each workspace.

  4. Commit Your Changes

    These guidelines should be kept in mind:

    • Progressive commit history, with clear separation of concerns.
    • Avoid individual commits that address specific review findings, which breaks commit history cohesion. Always fold review findings into the original commit.
    • Commit messages should provide a clear and concise explanation of the solution's rationale.
    • If the specific commit closes some specific github issue, include the issue URL in the commit message.
    • If possible, sign your commits with your GPG key.
    • Writing style: chris.beams.io/posts/git-commit
    • Structure: conventionalcommits.org

  5. Submit a Pull Request

    Once you're satisfied with your changes, submit a pull request to this repository. Provide a clear and concise description of the changes you've made. If your pull request addresses an existing issue, reference the issue number in the description. Every PR must be opened against the main branch.

  6. Review and Iterate

  7. Merge and Close

    Once your pull request has been approved and all discussions have been resolved, a project maintainer will merge your changes into the main branch. Your contribution will then be officially part of the project. The pull request will be closed, marking the completion of your contribution.

Monitoring API Schema

The monitoring module of stratum-apps exposes an HTTP API documented with OpenAPI. This schema is:

  1. Auto-generated: The openapi.json file is generated from code at compile time, not manually written
  2. CI-validated: Every PR that changes monitoring code must update openapi.json
  3. Synced to consumer: Changes trigger an issue in the sv2-ui repository

Updating the Schema

If you modify the monitoring HTTP server (endpoints, response types, etc.), you must regenerate the schema:

cd stratum-apps
cargo run --bin generate-openapi --features monitoring > src/monitoring/openapi.json

Then commit the updated file along with your code changes.

Why This Matters

The sv2-ui project consumes this schema to generate TypeScript types and API clients. Keeping it in sync ensures the frontend stays compatible with the backend.

API Compatibility Guidelines

When modifying the monitoring API, follow these guidelines:

  1. Keep existing fields backward-compatible - The /api/v1 endpoint fields should remain stable
  2. Add new data via optional fields or new endpoints - Don't modify existing response structures
  3. Don't change field types or semantics - Existing field definitions within the same API version are immutable

Versioning and public dependencies

Whenever submitting a PR that modifies some crate, it's up to the contributor to make sure the versioning of this crate remains sane. The main factors to take into account are:

  1. According to SemVer 2.0.0 and the modifications on this PR, what kind of version bump does this crate deserve?
  2. Avoiding redundant version bumps:
    • Has the version of crate already been bumped on this repo since it was last published to crates.io?
    • If yes, do the changes introduced by this PR require a larger bump than the one already made?
  3. Keeping sanity across dependency chains:
    • Which other crates on this repo depend on this crate?
    • Amongst them, are there types from this crate exposed on their public APIs?

Factors 1 and 2 are partially enforced via CI (but enforcement via PR review is still encouraged):

  • cargo semver-checks fails when the public API of a crate changed more than its version bump allows, using the latest version published on crates.io as the baseline.
  • scripts/check-version-bumps.sh fails when a crate has changes on the PR while its version is not above the highest version ever published on crates.io. Run ./scripts/check-version-bumps.sh origin/main locally to check your branch before opening a PR.

Factor 3 must be fully enforced via PR reviews.

Factor 2 is about avoiding redundant version bumps. Since crates are only published to crates.io periodically (during global release), maybe other PRs already bumped this crate version.

Factor 3 is about keeping sanity across dependency chains. If a crate only uses a dependency internally, updating that dependency does not automatically require an incompatible version bump for the dependent crate. However, if a dependency appears in the dependent crate's public API, then changing that dependency to an incompatible version also changes the dependent crate's public API. Either way the dependent crate needs some bump: an incompatible bump of a dependency invalidates the version requirement declared on the dependent crate's manifest, and once that manifest is updated CI requires the dependent crate to be bumped as well.

Public API exposure includes, but is not limited to:

  • re-exports;
  • public function or method arguments and return types;
  • public trait method signatures;
  • public enum variant payloads;
  • public struct fields;
  • public type aliases and associated types.

For crates that are already 1.0.0 or above, an incompatible version bump means a MAJOR bump. For 0.x.y crates, an incompatible version bump usually means a MINOR bump, for example 0.2.3 -> 0.3.0.

On every global release, a github issue (titled "version bumps for x.y.z" or similar) is used to keep track of all crate version bumps. If a PR is bumping some crate version, the PR author should take note on the corresponding issue.

Your First Code Contribution

In order to contribute, a basic learning about git and github is needed. If you're not familiar with them, have a look at https://docs.github.com/en/get-started/start-your-journey/git-and-github-learning-resources to dig into and learn how to use them.

Unsure where to begin contributing to SV2 Applications? You can start by looking through good first issue and help wanted issues:

  • Good first issue are issues which should only require a few lines of code, and a test or two.
  • Help wanted - issues which should be a bit more involved than good first issue issues.

For protocol-level contributions, also check the main SRI repository:

Another way to better understand where to focus your contribution is by looking at our roadmap: https://github.com/orgs/stratum-mining/projects/5