CONTRIBUTING.md 5.06 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 8 9 10 11
## Licensing

By contributing to libgit2, you agree to release your contribution under the terms of the license.
For code under `examples`, this is governed by the [CC0 Public Domain Dedication](examples/COPYING).
All other code is released under the [GPL v2 with linking exception](COPYING).

Ben Straub committed
12 13 14 15
## Discussion & Chat

We hang out in the #libgit2 channel on irc.freenode.net.

16 17 18 19 20
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.

Ben Straub committed
21 22
## Reporting Bugs

23 24 25 26 27 28 29 30 31 32 33
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.
[v0.17.0](https://github.com/libgit2/libgit2/tree/v0.17.0) ) or a commit
SHA (e.g.
[01be7863](https://github.com/libgit2/libgit2/commit/01be786319238fd6507a08316d1c265c1a89407f)
).  Using [`git describe`](http://git-scm.com/docs/git-describe) is a great
way to tell us what version you're working with.

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

35 36 37 38 39
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
40 41 42

## Pull Requests

43 44 45 46 47
Our work flow is a typical GitHub flow, where contributors fork the
[libgit2 repository](https://github.com/libgit2/libgit2), make their changes
on branch, and submit a
[Pull Request](https://help.github.com/articles/using-pull-requests)
(a.k.a. "PR").
Ben Straub committed
48

49 50 51 52 53 54 55
Life will be a lot easier for you (and us) if you follow this pattern
(i.e. fork, named branch, submit PR).  If you use your fork's `development`
branch, things can get messy.

Please include a nice description of your changes with 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.
Ben Straub committed
56

57 58 59 60 61 62
If you are working on a particular area then feel free to submit a PR that
highlights your work in progress (and flag in the PR title that it's not
ready to merge). This 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.

Ben Straub committed
63 64
## Porting Code From Other Open-Source Projects

65 66 67 68 69 70
`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
71
[`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
72
file for authors who have already consented.
Ben Straub committed
73

74 75 76 77
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
78

79
If you are pulling in code from core Git, another project or code you've pulled from
80 81 82
a forum / Stack Overflow then please flag this in your PR and also make sure you've
given proper credit to the original author in the code snippet.

83
## Style Guide
Ben Straub committed
84

85 86 87 88 89 90 91
`libgit2` is written in [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
(a.k.a. C89) with some specific conventions for function and type naming,
code formatting, and testing.

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
at the
Ben Straub committed
92
[conventions file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
Ben Straub committed
93

94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
## Starter Projects

So, you want to start helping out with `libgit2`? That's fantastic? We
welcome contributions and we promise we'll try to be nice.

If you want to jump in, you can look at our issues list to see if there
are any unresolved issues to jump in on.  Also, here is a list of some
smaller project ideas that could help you become familiar with the code
base and make a nice first step:

* Convert a `git_*modulename*_foreach()` callback-based iteration API
  into a `git_*modulename*_iterator` object with a create/advance style
  of API.  This helps folks writing language bindings and usually isn't
  too complicated.
* Write a new `examples/` program that mirrors a particular core git
  command.  (See `examples/diff.c` for example.)  This lets you (and us)
  easily exercise a particular facet of the API and measure compatability
  and feature parity with core git.
* Submit a PR to clarify documentation! While we do try to document all of
  the APIs, your fresh eyes on the documentation will find areas that are
  confusing much more easily.