|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thank you for considering making contributions to `arkworks-rs/r1cs-std`! |
| 4 | + |
| 5 | +Contributing to this repo can be done in several forms, such as participating in discussion or proposing code changes. |
| 6 | +To ensure a smooth workflow for all contributors, the following general procedure for contributing has been established: |
| 7 | + |
| 8 | +1) Either open or find an issue you'd like to help with |
| 9 | +2) Participate in thoughtful discussion on that issue |
| 10 | +3) If you would like to contribute: |
| 11 | + * If the issue is a feature proposal, ensure that the proposal has been accepted |
| 12 | + * Ensure that nobody else has already begun working on this issue. |
| 13 | + If they have, please try to contact them to collaborate |
| 14 | + * If nobody has been assigned for the issue and you would like to work on it, make a comment on the issue to inform the community of your intentions to begin work. (So we can avoid duplication of efforts) |
| 15 | + * We suggest using standard Github best practices for contributing: fork the repo, branch from the HEAD of `main`, make some commits on your branch, and submit a PR from the branch to `main`. |
| 16 | + More detail on this is below |
| 17 | + * Be sure to include a relevant change log entry in the Pending section of CHANGELOG.md (see file for log format) |
| 18 | + * If the change is breaking, we may add migration instructions. |
| 19 | + |
| 20 | +Note that for very small or clear problems (such as typos), or well isolated improvements, it is not required to an open issue to submit a PR. |
| 21 | +But be aware that for more complex problems/features touching multiple parts of the codebase, if a PR is opened before an adequate design discussion has taken place in a github issue, that PR runs a larger likelihood of being rejected. |
| 22 | + |
| 23 | +Looking for a good place to start contributing? How about checking out some good first issues |
| 24 | + |
| 25 | +## Branch Structure |
| 26 | + |
| 27 | +`r1cs-std` has its default branch as `main`, which is where PRs are merged into. Releases will be periodically made, on no set schedule. |
| 28 | +All other branches should be assumed to be miscellaneous feature development branches. |
| 29 | + |
| 30 | +All downstream users of the library should be using tagged versions of the library pulled from cargo. |
| 31 | + |
| 32 | +## How to work on a fork |
| 33 | +Please skip this section if you're familiar with contributing to opensource github projects. |
| 34 | + |
| 35 | +First fork the repo from the github UI, and clone it locally. |
| 36 | +Then in the repo, you want to add the repo you forked from as a new remote. You do this as: |
| 37 | +```bash |
| 38 | +git remote add upstream [email protected]:arkworks-rs/r1cs-std.git |
| 39 | +``` |
| 40 | + |
| 41 | +Then the way you make code contributions is to first think of a branch name that describes your change. |
| 42 | +Then do the following: |
| 43 | +```bash |
| 44 | +git checkout main |
| 45 | +git pull upstream main |
| 46 | +git checkout -b $NEW_BRANCH_NAME |
| 47 | +``` |
| 48 | +and then work as normal on that branch, and pull request to upstream master when you're done =) |
| 49 | + |
| 50 | +## Updating documentation |
| 51 | + |
| 52 | +All PRs should aim to leave the code more documented than it started with. |
| 53 | +Please don't assume that its easy to infer what the code is doing, |
| 54 | +as that is almost always not the case for these complex protocols. |
| 55 | +(Even when you understand the paper!) |
| 56 | + |
| 57 | +Its often very useful to describe what is the high level view of what a code block is doing, |
| 58 | +and either refer to the relevant section of a paper or include a short proof/argument for why it makes sense before the actual logic. |
| 59 | + |
| 60 | +## Performance improvements |
| 61 | + |
| 62 | +All performance improvements should be accompanied with benchmarks improving, or otherwise have it be clear that things have improved. |
| 63 | +For some areas of the codebase, performance roughly follows the number of field multiplications, but there are also many areas where |
| 64 | +hard to predict low level system effects such as cache locality and superscalar operations become important for performance. |
| 65 | +Thus performance can often become very non-intuitive / diverge from minimizing the number of arithmetic operations. |
0 commit comments