1# Contributing
 2
 3Thank you for considering making contributions to `arkworks-rs/r1cs-std`!
 4
 5Contributing to this repo can be done in several forms, such as participating in discussion or proposing code changes. 
 6To ensure a smooth workflow for all contributors, the following general procedure for contributing has been established:
 7
 81) Either open or find an issue you'd like to help with
 92) Participate in thoughtful discussion on that issue
103) 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
20Note 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.
21But 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
23Looking 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.
28All other branches should be assumed to be miscellaneous feature development branches.
29
30All downstream users of the library should be using tagged versions of the library pulled from cargo.
31
32## How to work on a fork
33Please skip this section if you're familiar with contributing to opensource github projects.
34
35First fork the repo from the github UI, and clone it locally.
36Then in the repo, you want to add the repo you forked from as a new remote. You do this as:
37```bash
38git remote add upstream git@github.com:arkworks-rs/r1cs-std.git
39```
40
41Then the way you make code contributions is to first think of a branch name that describes your change.
42Then do the following:
43```bash
44git checkout main
45git pull upstream main
46git checkout -b $NEW_BRANCH_NAME
47```
48and then work as normal on that branch, and pull request to upstream master when you're done =)
49
50## Updating documentation
51
52All PRs should aim to leave the code more documented than it started with.
53Please don't assume that its easy to infer what the code is doing,
54as that is almost always not the case for these complex protocols.
55(Even when you understand the paper!)
56
57Its often very useful to describe what is the high level view of what a code block is doing,
58and 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
62All performance improvements should be accompanied with benchmarks improving, or otherwise have it be clear that things have improved.
63For some areas of the codebase, performance roughly follows the number of field multiplications, but there are also many areas where
64hard to predict low level system effects such as cache locality and superscalar operations become important for performance.
65Thus performance can often become very non-intuitive / diverge from minimizing the number of arithmetic operations.