open source process docs first draft (MinaProtocol#906)

.github/ISSUE_TEMPLATES/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Coda is behaving strangely? Report it so we can fix it!
+---
+
+**Have you already searched the issue tracker to see if this bug has already
+been reported?**
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+1. First step
+2. Second step
+3. Third step
+4. Observe the bug
+
+If you can't reliably reproduce the issue, please describe the general
+conditions where you've observed the issue.
+
+**Expected behavior**
+What should have happened instead of the bug?
+
+**Output of `coda -version`**: Fill this in!
+
+**Log file**: Upload `debug.log` (`coda client log-location` tells you where it is) to https://gist.github.com/ and link here.
+
+**Additional context**: Any other notes? Is this related to other issues? Did
+anyone in Discord have anything to add?

.github/ISSUE_TEMPLATES/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Coda can't do something? Maybe it should!
+---
+
+**Have you already searched the issue tracker to see if this feature has already
+been requested?**
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATES/help.md

@@ -0,0 +1,7 @@
+---
+name: I have a question / I need help
+about: Please don't open an issue! Ask for help on Discord.
+---
+
+Issue trackers aren't a good place to ask questions or for help. Instead,
+contact us on the [Coda Discord](https://discord.gg/ShKhA7J)!

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+Thank you for contributing to Coda! Please see `CONTRIBUTING.md` if you haven't
+yet.
+
+Explain your changes here.
+
+Checklist:
+
+- [ ] Tests were added for the new behavior
+- [ ] All tests pass (CI will check this if you didn't)
+- [ ] This closes issues (list them): #0000

CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to Coda
+
+Thank you for your interest in contributing to Coda 😁. This file outlines
+various parts of our process. Coda is still very young, so things might be a
+little bumpy while we figure out how to smoothly run the project!
+
+If you haven't seen it yet, the [developer README](README-dev.md) has the
+basic setup you need to get up and running to build and edit Coda.
+
+## Bug reports
+
+Bug reports should include, at minimal, the `coda -version` output and
+a description of the error. See the [bug report
+template](.github/ISSUE_TEMPLATES/bug_report.md).
+
+All bugs need to be reproduced before they can be fixed. Anyone can try and
+reproduce a bug! If you have trouble reproducing a bug, please comment with what
+you tried. If it doesn't reproduce using exactly the steps in the issue report,
+please write a comment describing your new steps to reproduce, or what environment
+setup you had to do to reproduce.
+
+Maintainers should label bug reports with `bug`, and any other relevant labels.
+
+## Feature requests
+
+We'll consider any feature requests, although the most successful feature
+requests usually aren't immediately posted to the issue tracker. The most
+successful feature requests start with discussion in the community! See the
+[feature request template](.github/ISSUE_TEMPLATES/feature_request.md).
+
+Maintainers should label feature requests with `feature`, and any other relevant
+labels.
+
+## Pull Requests
+
+All pull requests go through CircleCI, which makes sure the code doesn't need to
+be reformatted, builds Coda in its various configurations, and runs all the
+tests.
+
+All pull requests must get _code reviewed_. Anyone can do a code review! Check
+out the [code review guide](docs/code_review.md) for what to look for. Just leave
+comments on the "Files changed" view.
+
+All pull requests must be approved by at least one member of the "core eng"
+team on github.
+
+Maintainers should assign reviewers to pull requests, and tag them with any
+relevant labels.
+
+## Documentation
+
+There are three main pieces of Coda documentation:
+
+1. The [`docs`](docs/) directory, which has prose documentation of various sorts. This
+   doesn't exist yet, but it should by the time this repo is made public!
+2. The `README.md` files in various directories. These explain the contents of that
+   directory at a high level: the purpose of the library, design constraints, anything else
+   specific to that directory.
+3. Inline code comments. There are very few of these, and we don't currently run ocamldoc
+   so they won't be exposed even as we write them. This should change eventually.
+
+Changes to the software should come with changes to the documentation.
+
+## RFCs
+
+The `rfcs` directory contains files documenting major changes to the software,
+how we work together, or the protocol. To make an RFC, just copy the
+`0000-template.md` to `0000-shortname.md` and fill it out! Then, open a pull
+request where the title starts with `[RFC]`. The idea is that we can discuss the
+RFC and come to consensus on what to do. Not all RFCs are merged, only the ones
+that we agree to implement.
+
+This process isn't final, but in general:
+
+1. RFCs will be open for at least a week for discussion.
+2. Once discussion has slowed down or there is consensus, the core eng team 
+   will initiate a "Final Comment Period". This will include the core eng's
+   "merge disposition" (merge/don't merge). The FCP comment should be based
+   on information and arguments already present in the RFC thread. At the 
+   end of the FCP, the core eng team decides to do another FCP, leave the FCP
+   state for continued discussion, or resolve the RFC by merging/closing
+   (whichever the announced disposition was).
+
+RFCs do not have to come with an implementation, and the RFC author isn't
+required to implement the PR.
+
+RFCs generally describe the design of a feature. As the code corresponding to
+the RFC changes, the RFC should be updated to reflect the current state of the
+code.
+
+This is loosely inspired by the Rust RFC process, Python PEPs, and IETF RFCs.
+
+## Release process
+
+Create a PR to merge master into testnet. Once that is approved by CI and checked in...
+
+```
+git checkout testnet
+git tag testnet-v0.$WHATEVER_IS_NEXT
+git push testnet-v0.$WHATEVER_IS_NEXT
+```
+
+Eventually, we will have a "stable" or "mainnet" branch. Once we do, the process will look like:
+
+Create a PR to merge testnet into stable. Once that is approved by CI and checked in...
+
+```
+git checkout stable
+git tag v1.$WHATEVER_IS_NEXT
+git push v1.$WHATEVER_IS_NEXT
+```
+
+And then do the above steps for testnet. Don't forget to deploy!
+
+## Issue/PR label guide
+
+We use them, although currently in a somewhat ad-hoc way. Please see
+https://github.com/CodaProtocol/coda/labels for the list of labels and their
+short descriptions. Any "complicated" labels should be described here.

README-dev.md

@@ -5,21 +5,39 @@ Coda is a new cryptocurrency protocol with a lightweight, constant sized blockch
 * [Coda Protocol Website](https://codaprotocol.com/)
 * [Coda Protocol Roadmap](https://github.com/orgs/CodaProtocol/projects/1)
 
-# Developer Setup
+If you haven't seen it yet, [CONTRIBUTING.md](CONTRIBUTING.md) has information
+about our development process and how to contribute. If you just want to build
+Coda, this is the right file!
 
-## Setup Docker CE on Linux
+# Building Coda
+
+Building Coda can be slightly involved. There are many C library dependencies that need
+to be present in the system, as well as some OCaml-specific setup.
+
+Currently, Coda only builds/runs on Linux. Building on macOS [is tracked in this issue](https://github.com/CodaProtocol/coda/issues/962).
+
+The short version:
+
+1. Install Docker, GNU make, and bash
+2. `make USEDOCKER=TRUE dev`
+3. `make USEDOCKER=TRUE deb`
+
+Now you'll have a `_build/codaclient.deb` ready to install on Ubuntu or Debian!
+
+## Developer Setup
+
+### Setup Docker CE on Linux
 [Ubuntu Setup Instructions](https://docs.docker.com/install/linux/docker-ce/ubuntu/)
 
-## Setup Google Cloud gcloud
+### Setup Google Cloud gcloud
 We use gcloud to store developer container images
 
 [Instructions to install gcloud sdk](https://cloud.google.com/sdk/install)
-(also install kubectl)
 
-## Take a Snapshot
+### Take a Snapshot
 If developing on a VM, now is a good time to take a snapshot and save your state.
 
-## Login and test gcloud access
+### Login and test gcloud access
 
 * Authorize gcloud with your o1 account\
 `gcloud auth login`
@@ -33,18 +51,12 @@ If developing on a VM, now is a good time to take a snapshot and save your state
 * Test gcloud/docker access\
 `docker run -it gcr.io/o1labs-192920/hellocoda`
 
-## Build a dev docker image
+### Build a dev docker image
 * clone this repository
 * Pull down dev container  (~7GB download, go stretch your legs)\
 `make docker`
 
-## Building outside docker
-You can see the dockerfiles for the opam deps we need. You can also
-do `opam switch import opam.export`. You'll also need to
-
-`opam pin add external/ocaml-sodium`
-
-## First code build
+### First code build
 
 * Change your shell path to include our scripts directory.\
 (REMEMBER to change the HOME and SOURCE directory to match yours)
@@ -56,7 +68,7 @@ export PATH=path/to/coda/scripts:$PATH
 * Start a build (go stretch your arms)\
 `make dev`
 
-## Customizing your dev environment for autocomplete/merlin
+### Customizing your dev environment for autocomplete/merlin
 
 * If you use vim, add this snippet in your vimrc to use merlin.\
 (REMEMBER to change the HOME directory to match yours)
@@ -69,25 +81,75 @@ let g:syntastic_ocaml_checkers=['merlin']
 ```
 
 * In your home directory `opam init`
-* In this shell, `eval \`opam config env\``* Now `/usr/bin/opam install merlin ocp-indent core async ppx_jane ppx_deriving` (everything we depend on, that you want autocompletes for) for doc reasons
+* In this shell, `eval $(opam config env)`
+* Now `/usr/bin/opam install merlin ocp-indent core async ppx_jane ppx_deriving` (everything we depend on, that you want autocompletes for) for doc reasons
 * Make sure you have `au FileType ocaml set omnifunc=merlin#Complete` in your vimrc
 * Install an auto-completer (such as YouCompleteMe) and a syntastic (such syntastic or ALE)
 
 * If you use vscode, you might like these extensions
    * [OCaml and Reason IDE](https://marketplace.visualstudio.com/items?itemName=freebroccolo.reasonml)
    * [Dune](https://marketplace.visualstudio.com/items?itemName=maelvalais.dune)
 
-# Docker Image Family Tree
+## Using the makefile
+
+The makefile contains phony targets for all the common tasks that need to be done.
+It also knows how to use Docker automatically. If you have `USEDOCKER=TRUE` in your
+environment, or run `make USEDOCKER=TRUE`, it will do the real work inside a container.
+You should probably use `USEDOCKER=TRUE` unless you've done the [building without docker](#building-without-docker) steps.
+
+These are the most important `make` targets:
+
+- `kademlia`: build the kademlia helper
+- `build`: build everything
+- `docker`: build the container
+- `container`: restart the development container (or start it if it's not yet)
+- `dev`: does `docker`, `container`, and `build`
+- `test`: run the tests
+- `web`: build the website, including the state explorer
+
+We use the [dune](https://github.com/ocaml/dune/) buildsystem for our OCaml code.
+
+NOTE: all of the `test-*` targets (including `test-all`) won't run in the container.
+`test` wraps them in the container.
+
+## Building outside docker
+
+Coda has a variety of opam and system dependencies.
+
+You can see [`Dockerfile-base`](/dockerfiles/Dockerfile-base) for how we
+install them all in the container. To get all the opam dependencies
+you need, you run `opam switch import src/opam.export`.
+
+Some of our dependencies aren't taken from `opam`, and aren't integrated
+with `dune`, so you need to add them manually:
+
+- `opam pin add src/external/ocaml-sodium`
+
+There are a variety of C libraries we expect to be available in the system.
+These are also listed in the dockerfiles.
+
+## Common dune tasks
+
+To run unit tests for a single library, do `dune runtest lib/$LIBNAME`.
+
+You can use `dune exec coda` to build and run `coda`. This is especially useful
+in the form of `dune exec coda -- integration-tests $SOME_TEST`.
+
+You might see a build error like this:
+
+```
+Error: Files external/digestif/src-c/.digestif_c.objs/digestif.cmx
+       and external/digestif/src-c/.digestif_c.objs/rakia.cmx
+       make inconsistent assumptions over implementation Rakia
+```
+
+You can work around it with `rm -r _build/default/src/$OFFENDING_PATH` and a rebuild.
+Here, the offending path is `external/digestif/src-c/.diestif_c.objs`.
+
+## Docker Image Family Tree
 
 Container Stages:
 * [ocaml/ocaml:debian-stable](https://hub.docker.com/r/ocaml/ocaml/) (community image, ~856MB) 
 * ocaml407 (built by us, stored in gcr, ~1.7GB)
-* ocaml-base (built by us, stored in gcr, ~7.1GB -- external dependancies and haskell)
-* nanotest (built with `make docker`, used with `make dev`, ~7.8GBm)
-
-# License
-
-This repository is distributed under the terms of the Apache 2.0 license,
-available in the LICENSE fail and online at
-https://www.apache.org/licenses/LICENSE-2.0. Commits older than 2018-10-03 do
-not have a LICENSE file or this notice, but are distributed under the same terms.
+* ocaml-base (built by us, stored in gcr, ~7.1GB -- external dependencies and haskell)
+* nanotest (built with `make docker`, used with `make dev`, ~7.8GB)

README.md

@@ -7,6 +7,10 @@ Coda is a new cryptocurrency protocol with a lightweight, constant sized blockch
 
 Please see our [developer README](README-dev.md) if you are interested in building coda from source code.
 
+We have a [Discord server]( https://discord.gg/ShKhA7J)! Please come by if you
+need help or have questions. You might also be interested in the [OCaml
+Discord](https://discordapp.com/invite/cCYQbqN), for general OCaml help.
+
 FIXME: Add some user documentation here.
 
 # Getting started

dockerfiles/Dockerfile-codaslim

@@ -1,6 +1,6 @@
 FROM debian:stretch-slim
 
-# Dependancies
+# Dependencies
 RUN apt-get -y update && \
   DEBIAN_FRONTEND=noninteractive apt-get -y upgrade && \
   DEBIAN_FRONTEND=noninteractive apt-get -y install \

docs/code_review.md

@@ -0,0 +1,24 @@
+# Coda code review guidelines
+
+A good pull request:
+
+- Does about one thing (new feature, bug fix, etc)
+- Adds tests and documentation for any new functionality
+- When fixing a bug, adds or fixes test that would have caught said bug
+
+## OCaml things
+
+- Are the [style guidelines](style_guidelines.md) being followed?
+- Do the signatures make sense? Are they minimal and reusable?
+- Does anything need to be functored over?
+- Are there any error cases that aren't handled correctly?
+- Are calls to `_exn` functions justified? Are their preconditions for not
+  throwing an exception met? Is the exception it throws useful?
+- There shouldn't be commented out code.
+- No stray debug code lying around.
+- Any logging is appropriate. All `Logger.trace` logs should be inessential,
+  because they won't be shown to anyone by default.
+- Should this code live in its library? Should it live in a different library?
+- Does the code confuse you? Maybe there should be a comment, or it should be
+  structured differently.
+- Does a behavior change break assumptions other code makes?