contributing.md 7.99 KB
Newer Older
Ben Straub committed
1 2 3 4 5
# Welcome to libgit2!

We're making it easy to do interesting things with git, and we'd love to have
your help.

6 7
## Licensing

8
By contributing to libgit2, you agree to release your contribution under
9 10 11
the terms of the license.  Except for the `examples` and the
`deps` directories, all code is released under the [GPL v2 with
linking exception](../COPYING).
12 13

The `examples` code is governed by the
14
[CC0 Public Domain Dedication](../examples/COPYING), so that you may copy
15
from them into your own application.
16

17 18 19 20
The bundled dependencies in the `deps` directories are governed
by the following licenses:

- http-parser is licensed under [MIT license](../deps/http-parser/COPYING)
21
- pcre is governed by [BSD license](../deps/pcre/LICENCE)
22 23 24
- winhttp is governed by [LGPL v2.1+](../deps/winhttp/COPYING.LGPL) and [GPL v2 with linking exception](../deps/winhttp/COPYING.GPL)
- zlib is governed by [zlib license](../deps/zlib/COPYING)

Ben Straub committed
25 26
## Discussion & Chat

27 28 29
We hang out in the
[`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
irc.freenode.net.
Ben Straub committed
30

31 32 33 34 35
Also, feel free to open an
[Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion
about any concerns you have.  We like to use Issues for that so there is an
easily accessible permanent record of the conversation.

36 37
## Libgit2 Versions

38
The `main` branch is the main branch where development happens.
39
Releases are tagged
Russell Belfer committed
40
(e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0) )
41 42 43
and when a critical bug fix needs to be backported, it will be done on a
`<tag>-maint` maintenance branch.

Ben Straub committed
44 45
## Reporting Bugs

46 47
First, know which version of libgit2 your problem is in and include it in
your bug report.  This can either be a tag (e.g.
48 49 50 51
[v0.17.0](https://github.com/libgit2/libgit2/releases/tag/v0.17.0)) or a
commit SHA
(e.g. [01be7863](https://github.com/libgit2/libgit2/commit/01be7863)).
Using [`git describe`](http://git-scm.com/docs/git-describe) is a
52
great way to tell us what version you're working with.
53

54
If you're not running against the latest `main` branch version,
55 56
please compile and test against that to avoid re-reporting an issue that's
already been fixed.
Ben Straub committed
57

58 59 60 61 62
It's *incredibly* helpful to be able to reproduce the problem.  Please
include a list of steps, a bit of code, and/or a zipped repository (if
possible).  Note that some of the libgit2 developers are employees of
GitHub, so if your repository is private, find us on IRC and we'll figure
out a way to help you.
Ben Straub committed
63 64 65

## Pull Requests

66 67 68
Our work flow is a [typical GitHub
flow](https://guides.github.com/introduction/flow/index.html), where
contributors fork the [libgit2 repository](https://github.com/libgit2/libgit2),
69
make their changes on branch, and submit a
70
[Pull Request](https://help.github.com/articles/using-pull-requests)
71
(a.k.a. "PR").  Pull requests should usually be targeted at the `main`
72
branch.
Ben Straub committed
73

74
Life will be a lot easier for you (and us) if you follow this pattern
75
(i.e. fork, named branch, submit PR).  If you use your fork's `main`
76 77 78 79 80 81 82
branch directly, things can get messy.

Please include a nice description of your changes when you submit your PR;
if we have to read the whole diff to figure out why you're contributing
in the first place, you're less likely to get feedback and have your change
merged in.

83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
In addition to outlining your thought process in the PR's description, please
also try to document it in your commits. We welcome it if every commit has a
description of why you have been doing your changes alongside with your
reasoning why this is a good idea. The messages shall be written in
present-tense and in an imperative style (e.g. "Add feature foobar", not "Added
feature foobar" or "Adding feature foobar"). Lines should be wrapped at 80
characters so people with small screens are able to read the commit messages in
their terminal without any problem.

To make it easier to attribute commits to certain parts of our code base, we
also prefer to have the commit subject be prefixed with a "scope". E.g. if you
are changing code in our merging subsystem, make sure to prefix the subject with
"merge:". The first word following the colon shall start with an lowercase
letter. The maximum line length for the subject is 70 characters, preferably
shorter.

99 100 101 102 103
If you are starting to work on a particular area, feel free to submit a PR
that highlights your work in progress (and note in the PR title that it's
not ready to merge). These early PRs are welcome and will help in getting
visibility for your fix, allow others to comment early on the changes and
also let others know that you are currently working on something.
104

105
Before wrapping up a PR, you should be sure to:
Ben Straub committed
106

107
* Write tests to cover any functional changes
108
* Update documentation for any changed public APIs
109
* Add to the [`changelog.md`](changelog.md) file describing any major changes
110

111 112 113 114 115 116 117 118 119 120 121
## Unit Tests

We believe that our unit tests allow us to keep the quality of libgit2
high: any new changes must not cause unit test failures, and new changes
should include unit tests that cover the bug fixes or new features.
For bug fixes, we prefer unit tests that illustrate the failure before
the change, but pass with your changes.

In addition to new tests, please ensure that your changes do not cause
any other test failures.  Running the entire test suite is helpful
before you submit a pull request.  When you build libgit2, the test
122
suite will also be built.  You can run most of the tests by simply running
123 124 125 126 127 128 129 130 131 132
the resultant `libgit2_clar` binary.  If you want to run a specific
unit test, you can name it with the `-s` option.  For example:

    libgit2_clar -sstatus::worktree::long_filenames

Or you can run an entire class of tests.  For example, to run all the
worktree status tests:

    libgit2_clar -sstatus::worktree

133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
The default test run is fairly exhaustive, but it will exclude some
unit tests by default: in particular, those that talk to network
servers and the tests that manipulate the filesystem in onerous
ways (and may need to have special privileges to run).  To run the
network tests:

    libgit2_clar -ionline

In addition, various tests may be enabled by environment variables,
like the ones that write exceptionally large repositories or manipulate
the filesystem structure in unexpected ways.  These tests *may be
dangerous* to run on a normal machine and may harm your filesystem.  It's
not recommended that you run these; instead, the continuous integration
servers will run these (in a sandbox).

Ben Straub committed
148 149
## Porting Code From Other Open-Source Projects

150 151 152 153 154 155
`libgit2` is licensed under the terms of the GPL v2 with a linking
exception.  Any code brought in must be compatible with those terms.

The most common case is porting code from core Git.  Git is a pure GPL
project, which means that in order to port code to this project, we need the
explicit permission of the author.  Check the
Ben Straub committed
156
[`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
157
file for authors who have already consented.
Ben Straub committed
158

159 160 161 162
Other licenses have other requirements; check the license of the library
you're porting code *from* to see what you need to do.  As a general rule,
MIT and BSD (3-clause) licenses are typically no problem.  Apache 2.0
license typically doesn't work due to GPL incompatibility.
Ben Straub committed
163

164 165 166 167
If your pull request uses code from core Git, another project, or code
from a forum / Stack Overflow, then *please* flag this in your PR and make
sure you've given proper credit to the original author in the code
snippet.
168

169
## Style Guide
Ben Straub committed
170

171 172
The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
(a.k.a. C89) compatible.  Internally, `libgit2` is written using a portable
Russell Belfer committed
173
subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep
174 175 176
local variable declarations at the tops of blocks only and avoid `//` style
comments.  Additionally, `libgit2` follows some extra conventions for
function and type naming, code formatting, and testing.
177 178 179

We like to keep the source code consistent and easy to read.  Maintaining
this takes some discipline, but it's been more than worth it.  Take a look
180
at the [conventions file](conventions.md).
Ben Straub committed
181

182 183
## Starter Projects

184
See our [projects list](projects.md).