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