[libgit2.git] / CONTRIBUTING.md

# Welcome to libgit2!

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

## Licensing

By contributing to libgit2, you agree to release your contribution under
the terms of the license.  Except for the `examples` directory, all code
is released under the [GPL v2 with linking exception](COPYING).

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

## Discussion & Chat

We hang out in the
[`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
irc.freenode.net.

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.

## Libgit2 Versions

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

## Reporting Bugs

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/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
great way to tell us what version you're working with.

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

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.

## Pull Requests

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),
make their changes on branch, and submit a
[Pull Request](https://help.github.com/articles/using-pull-requests)
(a.k.a. "PR").  Pull requests should usually be targeted at the `master`
branch.

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 `master`
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.

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.

Before wrapping up a PR, you should be sure to:

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

## 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
suite will also be built.  You can run all tests by simply running
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

## Porting Code From Other Open-Source Projects

`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
[`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
file for authors who have already consented.

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.

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.

## Style Guide

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
subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep
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.

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 [conventions
file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).

## Starter Projects

See our [projects
list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).
Commit	Line	Data
41b00ccc BS	1	# Welcome to libgit2!
	2
	3	We're making it easy to do interesting things with git, and we'd love to have
	4	your help.
	5
dcfdb977 BS	6	## Licensing
dcfdb977 BS	7
68a19ca9 RB	8	By contributing to libgit2, you agree to release your contribution under
	9	the terms of the license. Except for the `examples` directory, all code
	10	is released under the [GPL v2 with linking exception](COPYING).
	11
	12	The `examples` code is governed by the
	13	[CC0 Public Domain Dedication](examples/COPYING), so that you may copy
	14	from them into your own application.
dcfdb977	15
41b00ccc BS	16	## Discussion & Chat
41b00ccc BS	17
ac63149c WP	18	We hang out in the
	19	[`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
	20	irc.freenode.net.
41b00ccc	21
1631147c RB	22	Also, feel free to open an
	23	[Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion
	24	about any concerns you have. We like to use Issues for that so there is an
	25	easily accessible permanent record of the conversation.
	26
a142ed91 RB	27	## Libgit2 Versions
	28
	29	The `master` branch is the main branch where development happens.
	30	Releases are tagged
b247a39d	31	(e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0) )
a142ed91 RB	32	and when a critical bug fix needs to be backported, it will be done on a
	33	`<tag>-maint` maintenance branch.
	34
41b00ccc BS	35	## Reporting Bugs
41b00ccc BS	36
1631147c RB	37	First, know which version of libgit2 your problem is in and include it in
1631147c RB	38	your bug report. This can either be a tag (e.g.
ac63149c WP	39	[v0.17.0](https://github.com/libgit2/libgit2/releases/tag/v0.17.0)) or a
	40	commit SHA
	41	(e.g. [01be7863](https://github.com/libgit2/libgit2/commit/01be7863)).
	42	Using [`git describe`](http://git-scm.com/docs/git-describe) is a
a142ed91	43	great way to tell us what version you're working with.
1631147c	44
a142ed91	45	If you're not running against the latest `master` branch version,
1631147c RB	46	please compile and test against that to avoid re-reporting an issue that's
1631147c RB	47	already been fixed.
41b00ccc	48
1631147c RB	49	It's incredibly helpful to be able to reproduce the problem. Please
	50	include a list of steps, a bit of code, and/or a zipped repository (if
	51	possible). Note that some of the libgit2 developers are employees of
	52	GitHub, so if your repository is private, find us on IRC and we'll figure
	53	out a way to help you.
41b00ccc BS	54
	55	## Pull Requests
	56
09846fd1 ET	57	Our work flow is a [typical GitHub
	58	flow](https://guides.github.com/introduction/flow/index.html), where
	59	contributors fork the [libgit2 repository](https://github.com/libgit2/libgit2),
a142ed91	60	make their changes on branch, and submit a
09846fd1 ET	61	[Pull Request](https://help.github.com/articles/using-pull-requests)
	62	(a.k.a. "PR"). Pull requests should usually be targeted at the `master`
	63	branch.
41b00ccc	64
1631147c	65	Life will be a lot easier for you (and us) if you follow this pattern
a142ed91 RB	66	(i.e. fork, named branch, submit PR). If you use your fork's `master`
	67	branch directly, things can get messy.
	68
	69	Please include a nice description of your changes when you submit your PR;
	70	if we have to read the whole diff to figure out why you're contributing
	71	in the first place, you're less likely to get feedback and have your change
	72	merged in.
	73
	74	If you are starting to work on a particular area, feel free to submit a PR
	75	that highlights your work in progress (and note in the PR title that it's
	76	not ready to merge). These early PRs are welcome and will help in getting
	77	visibility for your fix, allow others to comment early on the changes and
	78	also let others know that you are currently working on something.
1631147c	79
a142ed91	80	Before wrapping up a PR, you should be sure to:
41b00ccc	81
09846fd1	82	* Write tests to cover any functional changes
a142ed91 RB	83	* Update documentation for any changed public APIs
a142ed91 RB	84	* Add to the [`CHANGELOG.md`](CHANGELOG.md) file describing any major changes
6ca83665	85
09846fd1 ET	86	## Unit Tests
	87
	88	We believe that our unit tests allow us to keep the quality of libgit2
	89	high: any new changes must not cause unit test failures, and new changes
	90	should include unit tests that cover the bug fixes or new features.
	91	For bug fixes, we prefer unit tests that illustrate the failure before
	92	the change, but pass with your changes.
	93
	94	In addition to new tests, please ensure that your changes do not cause
	95	any other test failures. Running the entire test suite is helpful
	96	before you submit a pull request. When you build libgit2, the test
	97	suite will also be built. You can run all tests by simply running
	98	the resultant `libgit2_clar` binary. If you want to run a specific
	99	unit test, you can name it with the `-s` option. For example:
	100
	101	libgit2_clar -sstatus::worktree::long_filenames
	102
	103	Or you can run an entire class of tests. For example, to run all the
	104	worktree status tests:
	105
	106	libgit2_clar -sstatus::worktree
	107
41b00ccc BS	108	## Porting Code From Other Open-Source Projects
41b00ccc BS	109
1631147c RB	110	`libgit2` is licensed under the terms of the GPL v2 with a linking
	111	exception. Any code brought in must be compatible with those terms.
	112
	113	The most common case is porting code from core Git. Git is a pure GPL
	114	project, which means that in order to port code to this project, we need the
	115	explicit permission of the author. Check the
41b00ccc	116	[`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
6ca83665	117	file for authors who have already consented.
41b00ccc	118
1631147c RB	119	Other licenses have other requirements; check the license of the library
	120	you're porting code from to see what you need to do. As a general rule,
	121	MIT and BSD (3-clause) licenses are typically no problem. Apache 2.0
	122	license typically doesn't work due to GPL incompatibility.
41b00ccc	123
a142ed91 RB	124	If your pull request uses code from core Git, another project, or code
	125	from a forum / Stack Overflow, then please flag this in your PR and make
	126	sure you've given proper credit to the original author in the code
	127	snippet.
6ca83665	128
1631147c	129	## Style Guide
41b00ccc	130
68a19ca9 RB	131	The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
68a19ca9 RB	132	(a.k.a. C89) compatible. Internally, `libgit2` is written using a portable
72556cc6	133	subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep
68a19ca9 RB	134	local variable declarations at the tops of blocks only and avoid `//` style
	135	comments. Additionally, `libgit2` follows some extra conventions for
	136	function and type naming, code formatting, and testing.
1631147c RB	137
	138	We like to keep the source code consistent and easy to read. Maintaining
	139	this takes some discipline, but it's been more than worth it. Take a look
09846fd1 ET	140	at the [conventions
09846fd1 ET	141	file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
41b00ccc	142
1631147c RB	143	## Starter Projects
1631147c RB	144
09846fd1 ET	145	See our [projects
09846fd1 ET	146	list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).