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