CONTRIBUTING.md 9.01 KB
Newer Older
1 2 3
# Contributing to Sia

#### Table of Contents
4
* [Get started with Go](#get-started-with-go)
5
  * [Install Go](#install-go)
6
  * [Learn Go](#learn-go)
7
* [Build Sia](#build-sia)
8 9 10 11 12 13
* [Contribute to the codebase](#contribute-to-the-codebase)
  * [Set up git](#set-up-git)
  * [Fork the Sia repository](#fork-the-sia-repository)
  * [Write some code](#write-some-code)
  * [Submit your code for review](#submit-your-code-for-review)
  * [More git resources](#more-git-resources)
14
* [Where to start](#where-to-start)
15
* [Contact us](#contact-us)
16

17 18 19
## Get started with Go

### Install Go
20

21 22 23 24 25 26 27 28
To install Go on your computer, follow the 
[official installation guide][install-go].  

You should install the latest [official Go binary][binary] for your system (if 
not available, [install from source][source]).  If you plan to cross compile 
Sia, see [Cross Compilation with Go 1.5][cross] by Dave Cheney.  

### Learn Go
29

30 31 32 33 34 35
* To get familiar with the language, start with the official [Tour of Go][tour].
* Move onto [How to Write Go Code][how] to learn how to organize Go packages 
and use the go tool.
* Finish with the [Effective Go][effective] guide.

## Build Sia
36

37 38 39 40
To build Sia on your machine, enter the following on the command line:

```bash
# Download Sia and its dependencies
Jane Maunsell's avatar
Jane Maunsell committed
41
# Binaries will be installed in $GOPATH/bin
42
$ go get -u gitlab.com/NebulousLabs/Sia/...
43 44

# Switch to directory containing Sia source code
45
$ cd $GOPATH/src/gitlab.com/NebulousLabs/Sia
46 47 48

# You have three Sia builds to choose from.
# To build the standard release binary:
49
$ make release
50 51
# Or to build the release binary with race detection and an array debugging 
# asserts:
52
$ make release-race
53 54
# Or to build the developer binary (with a different genesis block, faster 
# block times, and other changes):
55 56 57 58 59 60 61
$ make dev
# Or build the developer binary with race detection:
$ make dev-race
# Build the debugger binary:
$ make debug
# Or build debugger binary with race detection:
$ make debug-race
62 63 64
```

## Contribute to the codebase
65

66
### Set up git
67

68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
Install git on your machine according to [these instructions][install-git] in 
the Pro Git book.

You will first need to set up global settings using the command line.
```bash
$ git config --global user.name "Your Name"
$ git config --global user.email you@somedomain.com

# Tell git to remember your login information for a certain amount of time.
# Default time is 15 minutes:
$ git config --global credential.helper cache
# Or you can choose a different amount of time:
$ git config --global credential.helper "cache --timeout=[seconds]"

```
83

84
### Fork the Sia repository
85

Luke Champine's avatar
Luke Champine committed
86
While logged into your GitLab account, navigate to the [Sia repository][sia] 
87 88
and click the 'Fork' button in the upper righthand corner.  Your account now 
has a 'forked' copy of the original repo at 
Luke Champine's avatar
Luke Champine committed
89
`https://gitlab.com/<your GitLab username>/Sia`.
90 91

When you installed Sia using `go get`, the go tool put the Sia source code in 
92
$GOPATH/src/gitlab.com/NebulousLabs/Sia. Change to that directory and set up
93 94 95
your fork as a git [remote][remote]:

```bash
96
$ cd $GOPATH/src/gitlab.com/NebulousLabs/Sia
97
# Add your fork as a remote.  Name it whatever is convenient,
Luke Champine's avatar
Luke Champine committed
98 99
# e.g your GitLab username
$ git remote add <remote name> https://gitlab.com/<username>/Sia.git
100
# Or if you use an SSH key, create the remote with the following
Luke Champine's avatar
Luke Champine committed
101
$ git remote add <remote name> git@gitlab.com:<username>/Sia.git
102 103 104
```

### Write some code
105

106 107 108 109 110 111 112 113
Right now your git local repository only has one branch (called 'master' by 
default). If you want to make changes, add a new branch and make your changes 
there. You should maintain master as an up-to-date copy of the NebulousLabs/Sia 
repository's master branch.

To create and checkout a new branch:
```bash
# If you're not already in the right directory:
114
$ cd $GOPATH/src/gitlab.com/NebulousLabs/Sia
115 116 117 118 119 120 121
# Make sure you're on branch master
$ git checkout master
# Create and checkout a new branch
$ git checkout -b <branch>
```
Now write some code while the new branch is checked out.

122 123 124 125
Only implement one logical change per branch. If you're working on several
things at once, make multiple branches. To switch between branches you're
working on, you have to stash the changes in the branch you're switching from by
running `git stash`, which tucks away all changes since the last commit.
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143

```bash
# Stash changes to current branch.
$ git stash
# Checkout other branch.
$ git checkout <branch>
...
# Make changes
...
# Return to first branch:
$ git checkout <branch 1>
# View a list of stashes and their corresponding hashes.
$ git stash list
# Reapply changes from the stash you want to recover and remove that stash from.
# the list
$ git stash pop <hash>
```

144 145 146
To learn more about branching, see [Using the Fork-and-Branch Git
Workflow][branch] and [Pro Git - Branches in a Nutshell][nutshell]. For more on
stashing, see [Pro Git - Stashing and Cleaning][stashing].
147
  
148 149 150 151
Be sure to follow the conventions detailed in
[docs/Developers.md][developers.md] and [Merge
Requests.md](./docs/Merge%20Requests.md).  We will reject merge requests that do
not satisfy these best practices.  
152 153

Once you've finished making changes, stage and commit your changes then update 
Luke Champine's avatar
Luke Champine committed
154
your fork on GitLab:
155 156 157 158 159 160 161 162

```bash
# Make sure the code is up to date with the original repo:
$ git checkout master
$ git pull origin master
# Checkout branch with changes.
$ git checkout <branch>
$ git rebase master
163
# Before every merge request, you should run `make test-long`
164 165 166 167 168 169 170 171 172
# to test your code and fix formatting and style problems.
$ make test-long
# If all goes well, proceed to staging your changed files:
$ git add <changed files>
# Use `git status` to see what files have been staged.
$ git status
# Commit your changes. If you just run `commit`,  a text editor will pop up for 
# you to enter a description of your changes.
$ git commit -m "Add new tests for CommitSync method"
Luke Champine's avatar
Luke Champine committed
173
# Push the changes to your fork on GitLab, which you should have set up as a 
174 175 176
# remote already.
$ git push <fork remote> <branch>
```
177

178
### Submit your code for review
179

180
Once you've tested your new code and pushed changes to your fork, navigate to 
Luke Champine's avatar
Luke Champine committed
181
your fork at `https://gitlab.com/<username>/Sia` in your browser.  
182 183
Switch to the branch you've made changes on by selecting it from the list on the
upper left.  Then click 'New merge request' on the upper right.
184

185 186
Once you have made the merge request, we will review your code.  We will reject
code that is unsafe, difficult to read, or otherwise violates the conventions
187
outlined in our [Developers][developers.md] document.
188

Jane Maunsell's avatar
Jane Maunsell committed
189
Here's a sample code review comment:
190
![Screenshot](doc/assets/codereview.png)
Jane Maunsell's avatar
Jane Maunsell committed
191

192
If you want to tweak code for which you've already submitted a merge request,
Jane Maunsell's avatar
Jane Maunsell committed
193
push the updated code to your fork with `git push -f <fork remote> <branch>` and
194
summarize the changes you've made in a comment on the merge request page on
Luke Champine's avatar
Luke Champine committed
195
GitLab.
196

197
Once we have accepted your changes and merged them into the original repo, you
198 199 200 201 202 203
have some cleanup to do:

```bash
# Update local master branch to reflect changes in origin (the original 
# repo).
$ git pull origin master
204
# Delete the branch you made the merge request from.
205
$ git branch -d <branch>
Jane Maunsell's avatar
Jane Maunsell committed
206 207
# Delete the remote branch on your fork.
$ git push <fork remote> :<branch>
208 209 210
# Update your fork.
$ git push <fork remote> master
```
211

212
### More Git resources
213

Luke Champine's avatar
Luke Champine committed
214
  * [How to into git (and GitHub)][luke] by Luke Champine
215 216 217
  * [Official resources for learning Git][git]

## Where to start
218

219
If you'd like to contribute to Sia but don't have any specific ideas, writing 
220
tests is a good way to get your feet wet.  See [Running and Writing Tests for Sia](doc/Running%20and%20Writing%20Tests%20for%20Sia.md) to get started.
221

222
To learn more about how various parts of the code base work, head over to our [Resources](resources.md) page in our [doc](docs) folder.
223

224
## Contact us
225

226
Feel free to ask for help on the #core-dev channel on [discord][discord].
227 228 229

[binary]: https://golang.org/dl/
[branch]: http://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/
230 231
[cheney]: http://dave.cheney.net/2013/06/09/writing-table-driven-tests-in-go
[cross]: http://dave.cheney.net/2015/08/22/cross-compilation-with-go-1-5
232
[developers.md]: https://gitlab.com/NebulousLabs/Sia/blob/master/doc/Developers.md
233
[discord]: https://discord.gg/sia
234 235 236 237 238
[docs]: https://gitlab.com/NebulousLabs/Sia/tree/master/doc
[effective]: https://golang.org/doc/effective_go.html
[git]: https://git-scm.com/doc
[gofmt]: https://golang.org/cmd/gofmt/
[how]: https://golang.org/doc/code.html
239
[install-git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
240 241 242 243
[install-go]: https://golang.org/doc/install
[luke]: https://gist.github.com/lukechampine/6418449
[nutshell]: https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
[resources.md]: https://gitlab.com/NebulousLabs/Sia/blob/master/doc/Resources.md
244
[remote]: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes
245 246 247 248 249 250
[sia]: https://gitlab.com/NebulousLabs/Sia
[signup]: https://github.com/join?source=header-home
[source]: https://golang.org/doc/install/source
[stashing]: https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning
[test-doc]: https://gitlab.com/NebulousLabs/Sia/blob/master/doc/Testing.md
[tour]: https://tour.golang.org/welcome/1