github.com/fozzysec/SiaPrime@v0.0.0-20190612043147-66c8e8d11fe3/CONTRIBUTING.md (about) 1 # Contributing to SiaPrime 2 3 #### Table of Contents 4 * [Get started with Go](#go) 5 * [Install Go](#install-go) 6 * [Learn Go](#learn-go) 7 * [Build SiaPrime](#build-siaprime) 8 * [Contribute to the codebase](#contribute) 9 * [Set up git](#setup-git) 10 * [Fork the SiaPrime repository](#fork) 11 * [Write some code](#write) 12 * [Submit your code for review](#pull) 13 * [More git resources](#git-resources) 14 * [Where to start](#where-to-start) 15 * [Contact us](#contact) 16 17 <a name="go"/> 18 19 ## Get started with Go 20 21 <a name="install-go"/> 22 23 ### Install Go 24 25 To install Go on your computer, follow the 26 [official installation guide][install-go]. 27 28 You should install the latest [official Go binary][binary] for your system (if 29 not available, [install from source][source]). If you plan to cross compile 30 SiaPrime, see [Cross Compilation with Go 1.5][cross] by Dave Cheney. 31 32 <a name="learn-go"/> 33 34 ### Learn Go 35 36 * To get familiar with the language, start with the official [Tour of Go][tour]. 37 * Move onto [How to Write Go Code][how] to learn how to organize Go packages 38 and use the go tool. 39 * Finish with the [Effective Go][effective] guide. 40 41 <a name="build-siaprime"/> 42 43 ## Build SiaPrime 44 45 To build SiaPrime on your machine, enter the following on the command line: 46 47 ```bash 48 # Download Sia and its dependencies 49 # Binaries will be installed in $GOPATH/bin 50 $ go get -u gitlab.com/SiaPrime/SiaPrime/... 51 52 # Switch to directory containing Sia source code 53 $ cd $GOPATH/src/gitlab.com/SiaPrime/Sia 54 55 # You have three SiaPrime builds to choose from. 56 # To build the standard release binary: 57 $ make release 58 # Or to build the release binary with race detection and an array debugging 59 # asserts: 60 $ make release-race 61 # Or to build the developer binary (with a different genesis block, faster 62 # block times, and other changes): 63 $ make dev 64 # Or build the developer binary with race detection: 65 $ make dev-race 66 # Build the debugger binary: 67 $ make debug 68 # Or build debugger binary with race detection: 69 $ make debug-race 70 ``` 71 72 <a name="contribute"/> 73 74 ## Contribute to the codebase 75 76 <a name="setup-git"/> 77 78 ### Set up git 79 80 Install git on your machine according to [these instructions][install-git] in 81 the Pro Git book. 82 83 You will first need to set up global settings using the command line. 84 ```bash 85 $ git config --global user.name "Your Name" 86 $ git config --global user.email you@somedomain.com 87 88 # Tell git to remember your login information for a certain amount of time. 89 # Default time is 15 minutes: 90 $ git config --global credential.helper cache 91 # Or you can choose a different amount of time: 92 $ git config --global credential.helper "cache --timeout=[seconds]" 93 94 ``` 95 <a name="fork"/> 96 97 ### Fork the SiaPrime repository 98 99 While logged into your GitLab account, navigate to the [SiaPrime repository][siaprime] 100 and click the 'Fork' button in the upper right hand corner. Your account now 101 has a 'forked' copy of the original repo at 102 `https://gitlab.com/<your GitLab username>/Sia`. 103 104 When you installed SiaPrime using `go get`, the go tool put the SiaPrime source code in 105 $GOPATH/src/gitlab.com/SiaPrime/Sia. Change to that directory and set up 106 your fork as a git [remote][remote]: 107 108 ```bash 109 $ cd $GOPATH/src/gitlab.com/SiaPrime/Sia 110 # Add your fork as a remote. Name it whatever is convenient, 111 # e.g your GitLab username 112 $ git remote add <remote name> https://gitlab.com/<username>/Sia.git 113 # Or if you use an SSH key, create the remote with the following 114 $ git remote add <remote name> git@gitlab.com:<username>/Sia.git 115 ``` 116 117 <a name="write"/> 118 119 ### Write some code 120 121 Right now your git local repository only has one branch (called 'master' by 122 default). If you want to make changes, add a new branch and make your changes 123 there. You should maintain master as an up-to-date copy of the SiaPrime/Sia 124 repository's master branch. 125 126 To create and checkout a new branch: 127 ```bash 128 # If you're not already in the right directory: 129 $ cd $GOPATH/src/gitlab.com/SiaPrime/Sia 130 # Make sure you're on branch master 131 $ git checkout master 132 # Create and checkout a new branch 133 $ git checkout -b <branch> 134 ``` 135 Now write some code while the new branch is checked out. 136 137 Only implement one logical change per branch. If you're working on several 138 things at once, make multiple branches. To switch between branches you're 139 working on, you have to stash the changes in the branch you're switching from 140 by running `git stash`, which tucks away all changes since the last 141 commit. 142 143 ```bash 144 # Stash changes to current branch. 145 $ git stash 146 # Checkout other branch. 147 $ git checkout <branch> 148 ... 149 # Make changes 150 ... 151 # Return to first branch: 152 $ git checkout <branch 1> 153 # View a list of stashes and their corresponding hashes. 154 $ git stash list 155 # Reapply changes from the stash you want to recover and remove that stash from. 156 # the list 157 $ git stash pop <hash> 158 ``` 159 160 To learn more about branching, see 161 [Using the Fork-and-Branch Git Workflow][branch] and 162 [Pro Git - Branches in a Nutshell][nutshell]. 163 For more on stashing, see [Pro Git - Stashing and Cleaning][stashing]. 164 165 Be sure to follow the conventions detailed in 166 [docs/Developers.md][developers.md]. We will reject pull requests that do not 167 satisfy these best practices. 168 169 Once you've finished making changes, stage and commit your changes then update 170 your fork on GitLab: 171 172 ```bash 173 # Make sure the code is up to date with the original repo: 174 $ git checkout master 175 $ git pull origin master 176 # Checkout branch with changes. 177 $ git checkout <branch> 178 $ git rebase master 179 # Before every pull request, you should run `make test-long` 180 # to test your code and fix formatting and style problems. 181 $ make test-long 182 # If all goes well, proceed to staging your changed files: 183 $ git add <changed files> 184 # Use `git status` to see what files have been staged. 185 $ git status 186 # Commit your changes. If you just run `commit`, a text editor will pop up for 187 # you to enter a description of your changes. 188 $ git commit -m "Add new tests for CommitSync method" 189 # Push the changes to your fork on GitLab, which you should have set up as a 190 # remote already. 191 $ git push <fork remote> <branch> 192 ``` 193 <a name="pull"/> 194 195 ### Submit your code for review 196 197 Once you've tested your new code and pushed changes to your fork, navigate to 198 your fork at `https://gitlab.com/<username>/Sia` in your browser. 199 Switch to the branch you've made changes on by selecting it from the list on 200 the upper left. Then click 'New pull request' on the upper right. 201 202 Once you have made the pull request, we will review your code. We will reject 203 code that is unsafe, difficult to read, or otherwise violates the conventions 204 outlined in [docs/Developers.md][developers.md]. 205 206 Here's a sample code review comment: 207 ![Screenshot](assets/codereview.png) 208 209 If you want to tweak code for which you've already submitted a pull request, 210 push the updated code to your fork with `git push -f <fork remote> <branch>` and 211 summarize the changes you've made in a comment on the pull request page on 212 GitLab. 213 214 Once we have accepted your changes and merged them into the original repo, you 215 have some cleanup to do: 216 217 ```bash 218 # Update local master branch to reflect changes in origin (the original 219 # repo). 220 $ git pull origin master 221 # Delete the branch you made the pull request from. 222 $ git branch -d <branch> 223 # Delete the remote branch on your fork. 224 $ git push <fork remote> :<branch> 225 # Update your fork. 226 $ git push <fork remote> master 227 ``` 228 <a name="git-resources"/> 229 230 ### More Git resources 231 232 * [How to into git (and GitHub)][luke] by Luke Champine 233 * [Official resources for learning Git][git] 234 235 <a name="where-to-start"/> 236 237 ## Where to start 238 239 If you'd like to contribute to SiaPrime but don't have any specific ideas, writing 240 tests is a good way to get your feet wet. See [doc/Running and Writing Tests for SiaPrime.md](Running%20and%20Writing%20Tests%20for%20SiaPrime.md) to get started. 241 242 <a name="contact"/> 243 244 ## Contact us 245 246 Feel free to ask for help on the #core-dev channel on [discord][discord]. 247 248 [cross]: http://dave.cheney.net/2015/08/22/cross-compilation-with-go-1-5 249 [binary]: https://golang.org/dl/ 250 [source]: https://golang.org/doc/install/source 251 [tour]: https://tour.golang.org/welcome/1 252 [how]: https://golang.org/doc/code.html 253 [luke]: https://gist.github.com/lukechampine/6418449 254 [git]: https://git-scm.com/doc 255 [cheney]: http://dave.cheney.net/2013/06/09/writing-table-driven-tests-in-go 256 [install-go]: https://golang.org/doc/install 257 [signup]: https://github.com/join?source=header-home 258 [effective]: https://golang.org/doc/effective_go.html 259 [siaprime]: https://gitlab.com/SiaPrime/Sia 260 [branch]: http://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/ 261 [developers.md]: https://gitlab.com/SiaPrime/SiaPrime/blob/master/doc/Developers.md 262 [gofmt]: https://golang.org/cmd/gofmt/ 263 [nutshell]: https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell 264 [discord]: https://discord.gg/sia 265 [install-git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git 266 [test-doc]: https://gitlab.com/SiaPrime/SiaPrime/blob/master/doc/Testing.md 267 [stashing]: https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning 268 [remote]: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes