1# How to Contribute to Jaeger 2 3We'd love your help! 4 5Jaeger is [Apache 2.0 licensed](LICENSE) and accepts contributions via GitHub 6pull requests. This document outlines some of the conventions on development 7workflow, commit message formatting, contact points and other resources to make 8it easier to get your contribution accepted. 9 10We gratefully welcome improvements to documentation as well as to code. 11 12# Certificate of Origin 13 14By contributing to this project you agree to the [Developer Certificate of 15Origin](https://developercertificate.org/) (DCO). This document was created 16by the Linux Kernel community and is a simple statement that you, as a 17contributor, have the legal right to make the contribution. See the [DCO](DCO) 18file for details. 19 20## Getting Started 21 22This library uses [dep](https://golang.github.io/dep/) to manage dependencies. 23 24To get started, make sure you clone the Git repository into the correct location 25`github.com/uber/jaeger-client-go` relative to `$GOPATH`: 26 27``` 28mkdir -p $GOPATH/src/github.com/uber 29cd $GOPATH/src/github.com/uber 30git clone git@github.com:jaegertracing/jaeger-client-go.git jaeger-client-go 31cd jaeger-client-go 32git submodule update --init --recursive 33``` 34 35Then install dependencies and run the tests: 36 37``` 38make install 39make test 40``` 41 42## Imports grouping 43 44This projects follows the following pattern for grouping imports in Go files: 45 * imports from standard library 46 * imports from other projects 47 * imports from `jaeger-client-go` project 48 49For example: 50 51```go 52import ( 53 "fmt" 54 55 "github.com/uber/jaeger-lib/metrics" 56 "go.uber.org/zap" 57 58 "github.com/uber/jaeger-client-go/config" 59) 60``` 61 62## Making A Change 63 64*Before making any significant changes, please [open an 65issue](https://github.com/jaegertracing/jaeger-client-go/issues).* Discussing your proposed 66changes ahead of time will make the contribution process smooth for everyone. 67 68Once we've discussed your changes and you've got your code ready, make sure 69that tests are passing (`make test` or `make cover`) and open your PR. Your 70pull request is most likely to be accepted if it: 71 72* Includes tests for new functionality. 73* Follows the guidelines in [Effective 74 Go](https://golang.org/doc/effective_go.html) and the [Go team's common code 75 review comments](https://github.com/golang/go/wiki/CodeReviewComments). 76* Has a [good commit message](https://chris.beams.io/posts/git-commit/): 77 * Separate subject from body with a blank line 78 * Limit the subject line to 50 characters 79 * Capitalize the subject line 80 * Do not end the subject line with a period 81 * Use the imperative mood in the subject line 82 * Wrap the body at 72 characters 83 * Use the body to explain _what_ and _why_ instead of _how_ 84* Each commit must be signed by the author ([see below](#sign-your-work)). 85 86## License 87 88By contributing your code, you agree to license your contribution under the terms 89of the [Apache License](LICENSE). 90 91If you are adding a new file it should have a header like below. The easiest 92way to add such header is to run `make fmt`. 93 94``` 95// Copyright (c) 2017 The Jaeger Authors. 96// 97// Licensed under the Apache License, Version 2.0 (the "License"); 98// you may not use this file except in compliance with the License. 99// You may obtain a copy of the License at 100// 101// http://www.apache.org/licenses/LICENSE-2.0 102// 103// Unless required by applicable law or agreed to in writing, software 104// distributed under the License is distributed on an "AS IS" BASIS, 105// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 106// See the License for the specific language governing permissions and 107// limitations under the License. 108``` 109 110## Sign your work 111 112The sign-off is a simple line at the end of the explanation for the 113patch, which certifies that you wrote it or otherwise have the right to 114pass it on as an open-source patch. The rules are pretty simple: if you 115can certify the below (from 116[developercertificate.org](http://developercertificate.org/)): 117 118``` 119Developer Certificate of Origin 120Version 1.1 121 122Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 123660 York Street, Suite 102, 124San Francisco, CA 94110 USA 125 126Everyone is permitted to copy and distribute verbatim copies of this 127license document, but changing it is not allowed. 128 129 130Developer's Certificate of Origin 1.1 131 132By making a contribution to this project, I certify that: 133 134(a) The contribution was created in whole or in part by me and I 135 have the right to submit it under the open source license 136 indicated in the file; or 137 138(b) The contribution is based upon previous work that, to the best 139 of my knowledge, is covered under an appropriate open source 140 license and I have the right under that license to submit that 141 work with modifications, whether created in whole or in part 142 by me, under the same open source license (unless I am 143 permitted to submit under a different license), as indicated 144 in the file; or 145 146(c) The contribution was provided directly to me by some other 147 person who certified (a), (b) or (c) and I have not modified 148 it. 149 150(d) I understand and agree that this project and the contribution 151 are public and that a record of the contribution (including all 152 personal information I submit with it, including my sign-off) is 153 maintained indefinitely and may be redistributed consistent with 154 this project or the open source license(s) involved. 155``` 156 157then you just add a line to every git commit message: 158 159 Signed-off-by: Joe Smith <joe@gmail.com> 160 161using your real name (sorry, no pseudonyms or anonymous contributions.) 162 163You can add the sign off when creating the git commit via `git commit -s`. 164 165If you want this to be automatic you can set up some aliases: 166 167``` 168git config --add alias.amend "commit -s --amend" 169git config --add alias.c "commit -s" 170``` 171