]>
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 |
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 |
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 |
36 | ||
1631147c RB |
37 | First, know which version of libgit2 your problem is in and include it in |
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 |
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 | ||
eae0bfdc PP |
74 | In addition to outlining your thought process in the PR's description, please |
75 | also try to document it in your commits. We welcome it if every commit has a | |
76 | description of why you have been doing your changes alongside with your | |
77 | reasoning why this is a good idea. The messages shall be written in | |
78 | present-tense and in an imperative style (e.g. "Add feature foobar", not "Added | |
79 | feature foobar" or "Adding feature foobar"). Lines should be wrapped at 80 | |
80 | characters so people with small screens are able to read the commit messages in | |
81 | their terminal without any problem. | |
82 | ||
83 | To make it easier to attribute commits to certain parts of our code base, we | |
84 | also prefer to have the commit subject be prefixed with a "scope". E.g. if you | |
85 | are changing code in our merging subsystem, make sure to prefix the subject with | |
86 | "merge:". The first word following the colon shall start with an lowercase | |
87 | letter. The maximum line length for the subject is 70 characters, preferably | |
88 | shorter. | |
89 | ||
a142ed91 RB |
90 | If you are starting to work on a particular area, feel free to submit a PR |
91 | that highlights your work in progress (and note in the PR title that it's | |
92 | not ready to merge). These early PRs are welcome and will help in getting | |
93 | visibility for your fix, allow others to comment early on the changes and | |
94 | also let others know that you are currently working on something. | |
1631147c | 95 | |
a142ed91 | 96 | Before wrapping up a PR, you should be sure to: |
41b00ccc | 97 | |
09846fd1 | 98 | * Write tests to cover any functional changes |
a142ed91 RB |
99 | * Update documentation for any changed public APIs |
100 | * Add to the [`CHANGELOG.md`](CHANGELOG.md) file describing any major changes | |
6ca83665 | 101 | |
09846fd1 ET |
102 | ## Unit Tests |
103 | ||
104 | We believe that our unit tests allow us to keep the quality of libgit2 | |
105 | high: any new changes must not cause unit test failures, and new changes | |
106 | should include unit tests that cover the bug fixes or new features. | |
107 | For bug fixes, we prefer unit tests that illustrate the failure before | |
108 | the change, but pass with your changes. | |
109 | ||
110 | In addition to new tests, please ensure that your changes do not cause | |
111 | any other test failures. Running the entire test suite is helpful | |
112 | before you submit a pull request. When you build libgit2, the test | |
1308059d | 113 | suite will also be built. You can run most of the tests by simply running |
09846fd1 ET |
114 | the resultant `libgit2_clar` binary. If you want to run a specific |
115 | unit test, you can name it with the `-s` option. For example: | |
116 | ||
117 | libgit2_clar -sstatus::worktree::long_filenames | |
118 | ||
119 | Or you can run an entire class of tests. For example, to run all the | |
120 | worktree status tests: | |
121 | ||
122 | libgit2_clar -sstatus::worktree | |
123 | ||
1308059d ET |
124 | The default test run is fairly exhaustive, but it will exclude some |
125 | unit tests by default: in particular, those that talk to network | |
126 | servers and the tests that manipulate the filesystem in onerous | |
127 | ways (and may need to have special privileges to run). To run the | |
128 | network tests: | |
129 | ||
130 | libgit2_clar -ionline | |
131 | ||
132 | In addition, various tests may be enabled by environment variables, | |
133 | like the ones that write exceptionally large repositories or manipulate | |
134 | the filesystem structure in unexpected ways. These tests *may be | |
135 | dangerous* to run on a normal machine and may harm your filesystem. It's | |
136 | not recommended that you run these; instead, the continuous integration | |
137 | servers will run these (in a sandbox). | |
138 | ||
41b00ccc BS |
139 | ## Porting Code From Other Open-Source Projects |
140 | ||
1631147c RB |
141 | `libgit2` is licensed under the terms of the GPL v2 with a linking |
142 | exception. Any code brought in must be compatible with those terms. | |
143 | ||
144 | The most common case is porting code from core Git. Git is a pure GPL | |
145 | project, which means that in order to port code to this project, we need the | |
146 | explicit permission of the author. Check the | |
41b00ccc | 147 | [`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors) |
6ca83665 | 148 | file for authors who have already consented. |
41b00ccc | 149 | |
1631147c RB |
150 | Other licenses have other requirements; check the license of the library |
151 | you're porting code *from* to see what you need to do. As a general rule, | |
152 | MIT and BSD (3-clause) licenses are typically no problem. Apache 2.0 | |
153 | license typically doesn't work due to GPL incompatibility. | |
41b00ccc | 154 | |
a142ed91 RB |
155 | If your pull request uses code from core Git, another project, or code |
156 | from a forum / Stack Overflow, then *please* flag this in your PR and make | |
157 | sure you've given proper credit to the original author in the code | |
158 | snippet. | |
6ca83665 | 159 | |
1631147c | 160 | ## Style Guide |
41b00ccc | 161 | |
68a19ca9 RB |
162 | The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C) |
163 | (a.k.a. C89) compatible. Internally, `libgit2` is written using a portable | |
72556cc6 | 164 | subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep |
68a19ca9 RB |
165 | local variable declarations at the tops of blocks only and avoid `//` style |
166 | comments. Additionally, `libgit2` follows some extra conventions for | |
167 | function and type naming, code formatting, and testing. | |
1631147c RB |
168 | |
169 | We like to keep the source code consistent and easy to read. Maintaining | |
170 | this takes some discipline, but it's been more than worth it. Take a look | |
09846fd1 ET |
171 | at the [conventions |
172 | file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md). | |
41b00ccc | 173 | |
1631147c RB |
174 | ## Starter Projects |
175 | ||
09846fd1 ET |
176 | See our [projects |
177 | list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md). |