Blame CONTRIBUTING.md

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).