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