|
Packit |
ae9e2a |
# Welcome to libgit2!
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
We're making it easy to do interesting things with git, and we'd love to have
|
|
Packit |
ae9e2a |
your help.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Licensing
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
By contributing to libgit2, you agree to release your contribution under
|
|
Packit |
ae9e2a |
the terms of the license. Except for the `examples` directory, all code
|
|
Packit |
ae9e2a |
is released under the [GPL v2 with linking exception](COPYING).
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
The `examples` code is governed by the
|
|
Packit |
ae9e2a |
[CC0 Public Domain Dedication](examples/COPYING), so that you may copy
|
|
Packit |
ae9e2a |
from them into your own application.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Discussion & Chat
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
We hang out in the
|
|
Packit |
ae9e2a |
[`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
|
|
Packit |
ae9e2a |
irc.freenode.net.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
Also, feel free to open an
|
|
Packit |
ae9e2a |
[Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion
|
|
Packit |
ae9e2a |
about any concerns you have. We like to use Issues for that so there is an
|
|
Packit |
ae9e2a |
easily accessible permanent record of the conversation.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Libgit2 Versions
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
The `master` branch is the main branch where development happens.
|
|
Packit |
ae9e2a |
Releases are tagged
|
|
Packit |
ae9e2a |
(e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0) )
|
|
Packit |
ae9e2a |
and when a critical bug fix needs to be backported, it will be done on a
|
|
Packit |
ae9e2a |
`<tag>-maint` maintenance branch.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Reporting Bugs
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
First, know which version of libgit2 your problem is in and include it in
|
|
Packit |
ae9e2a |
your bug report. This can either be a tag (e.g.
|
|
Packit |
ae9e2a |
[v0.17.0](https://github.com/libgit2/libgit2/releases/tag/v0.17.0)) or a
|
|
Packit |
ae9e2a |
commit SHA
|
|
Packit |
ae9e2a |
(e.g. [01be7863](https://github.com/libgit2/libgit2/commit/01be7863)).
|
|
Packit |
ae9e2a |
Using [`git describe`](http://git-scm.com/docs/git-describe) is a
|
|
Packit |
ae9e2a |
great way to tell us what version you're working with.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
If you're not running against the latest `master` branch version,
|
|
Packit |
ae9e2a |
please compile and test against that to avoid re-reporting an issue that's
|
|
Packit |
ae9e2a |
already been fixed.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
It's *incredibly* helpful to be able to reproduce the problem. Please
|
|
Packit |
ae9e2a |
include a list of steps, a bit of code, and/or a zipped repository (if
|
|
Packit |
ae9e2a |
possible). Note that some of the libgit2 developers are employees of
|
|
Packit |
ae9e2a |
GitHub, so if your repository is private, find us on IRC and we'll figure
|
|
Packit |
ae9e2a |
out a way to help you.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Pull Requests
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
Our work flow is a [typical GitHub
|
|
Packit |
ae9e2a |
flow](https://guides.github.com/introduction/flow/index.html), where
|
|
Packit |
ae9e2a |
contributors fork the [libgit2 repository](https://github.com/libgit2/libgit2),
|
|
Packit |
ae9e2a |
make their changes on branch, and submit a
|
|
Packit |
ae9e2a |
[Pull Request](https://help.github.com/articles/using-pull-requests)
|
|
Packit |
ae9e2a |
(a.k.a. "PR"). Pull requests should usually be targeted at the `master`
|
|
Packit |
ae9e2a |
branch.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
Life will be a lot easier for you (and us) if you follow this pattern
|
|
Packit |
ae9e2a |
(i.e. fork, named branch, submit PR). If you use your fork's `master`
|
|
Packit |
ae9e2a |
branch directly, things can get messy.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
Please include a nice description of your changes when you submit your PR;
|
|
Packit |
ae9e2a |
if we have to read the whole diff to figure out why you're contributing
|
|
Packit |
ae9e2a |
in the first place, you're less likely to get feedback and have your change
|
|
Packit |
ae9e2a |
merged in.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
If you are starting to work on a particular area, feel free to submit a PR
|
|
Packit |
ae9e2a |
that highlights your work in progress (and note in the PR title that it's
|
|
Packit |
ae9e2a |
not ready to merge). These early PRs are welcome and will help in getting
|
|
Packit |
ae9e2a |
visibility for your fix, allow others to comment early on the changes and
|
|
Packit |
ae9e2a |
also let others know that you are currently working on something.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
Before wrapping up a PR, you should be sure to:
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
* Write tests to cover any functional changes
|
|
Packit |
ae9e2a |
* Update documentation for any changed public APIs
|
|
Packit |
ae9e2a |
* Add to the [`CHANGELOG.md`](CHANGELOG.md) file describing any major changes
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Unit Tests
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
We believe that our unit tests allow us to keep the quality of libgit2
|
|
Packit |
ae9e2a |
high: any new changes must not cause unit test failures, and new changes
|
|
Packit |
ae9e2a |
should include unit tests that cover the bug fixes or new features.
|
|
Packit |
ae9e2a |
For bug fixes, we prefer unit tests that illustrate the failure before
|
|
Packit |
ae9e2a |
the change, but pass with your changes.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
In addition to new tests, please ensure that your changes do not cause
|
|
Packit |
ae9e2a |
any other test failures. Running the entire test suite is helpful
|
|
Packit |
ae9e2a |
before you submit a pull request. When you build libgit2, the test
|
|
Packit |
ae9e2a |
suite will also be built. You can run most of the tests by simply running
|
|
Packit |
ae9e2a |
the resultant `libgit2_clar` binary. If you want to run a specific
|
|
Packit |
ae9e2a |
unit test, you can name it with the `-s` option. For example:
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
libgit2_clar -sstatus::worktree::long_filenames
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
Or you can run an entire class of tests. For example, to run all the
|
|
Packit |
ae9e2a |
worktree status tests:
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
libgit2_clar -sstatus::worktree
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
The default test run is fairly exhaustive, but it will exclude some
|
|
Packit |
ae9e2a |
unit tests by default: in particular, those that talk to network
|
|
Packit |
ae9e2a |
servers and the tests that manipulate the filesystem in onerous
|
|
Packit |
ae9e2a |
ways (and may need to have special privileges to run). To run the
|
|
Packit |
ae9e2a |
network tests:
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
libgit2_clar -ionline
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
In addition, various tests may be enabled by environment variables,
|
|
Packit |
ae9e2a |
like the ones that write exceptionally large repositories or manipulate
|
|
Packit |
ae9e2a |
the filesystem structure in unexpected ways. These tests *may be
|
|
Packit |
ae9e2a |
dangerous* to run on a normal machine and may harm your filesystem. It's
|
|
Packit |
ae9e2a |
not recommended that you run these; instead, the continuous integration
|
|
Packit |
ae9e2a |
servers will run these (in a sandbox).
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Porting Code From Other Open-Source Projects
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
`libgit2` is licensed under the terms of the GPL v2 with a linking
|
|
Packit |
ae9e2a |
exception. Any code brought in must be compatible with those terms.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
The most common case is porting code from core Git. Git is a pure GPL
|
|
Packit |
ae9e2a |
project, which means that in order to port code to this project, we need the
|
|
Packit |
ae9e2a |
explicit permission of the author. Check the
|
|
Packit |
ae9e2a |
[`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
|
|
Packit |
ae9e2a |
file for authors who have already consented.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
Other licenses have other requirements; check the license of the library
|
|
Packit |
ae9e2a |
you're porting code *from* to see what you need to do. As a general rule,
|
|
Packit |
ae9e2a |
MIT and BSD (3-clause) licenses are typically no problem. Apache 2.0
|
|
Packit |
ae9e2a |
license typically doesn't work due to GPL incompatibility.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
If your pull request uses code from core Git, another project, or code
|
|
Packit |
ae9e2a |
from a forum / Stack Overflow, then *please* flag this in your PR and make
|
|
Packit |
ae9e2a |
sure you've given proper credit to the original author in the code
|
|
Packit |
ae9e2a |
snippet.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Style Guide
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
|
|
Packit |
ae9e2a |
(a.k.a. C89) compatible. Internally, `libgit2` is written using a portable
|
|
Packit |
ae9e2a |
subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep
|
|
Packit |
ae9e2a |
local variable declarations at the tops of blocks only and avoid `//` style
|
|
Packit |
ae9e2a |
comments. Additionally, `libgit2` follows some extra conventions for
|
|
Packit |
ae9e2a |
function and type naming, code formatting, and testing.
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
We like to keep the source code consistent and easy to read. Maintaining
|
|
Packit |
ae9e2a |
this takes some discipline, but it's been more than worth it. Take a look
|
|
Packit |
ae9e2a |
at the [conventions
|
|
Packit |
ae9e2a |
file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
## Starter Projects
|
|
Packit |
ae9e2a |
|
|
Packit |
ae9e2a |
See our [projects
|
|
Packit |
ae9e2a |
list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).
|