]>
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 | 8 | By contributing to libgit2, you agree to release your contribution under |
ac3d33df JK |
9 | the terms of the license. Except for the `examples` and the |
10 | `deps` directories, all code is released under the [GPL v2 with | |
11 | linking exception](../COPYING). | |
68a19ca9 RB |
12 | |
13 | The `examples` code is governed by the | |
ac3d33df | 14 | [CC0 Public Domain Dedication](../examples/COPYING), so that you may copy |
68a19ca9 | 15 | from them into your own application. |
dcfdb977 | 16 | |
ac3d33df JK |
17 | The bundled dependencies in the `deps` directories are governed |
18 | by the following licenses: | |
19 | ||
20 | - http-parser is licensed under [MIT license](../deps/http-parser/COPYING) | |
c25aa7cd | 21 | - pcre is governed by [BSD license](../deps/pcre/LICENCE) |
ac3d33df JK |
22 | - winhttp is governed by [LGPL v2.1+](../deps/winhttp/COPYING.LGPL) and [GPL v2 with linking exception](../deps/winhttp/COPYING.GPL) |
23 | - zlib is governed by [zlib license](../deps/zlib/COPYING) | |
24 | ||
41b00ccc BS |
25 | ## Discussion & Chat |
26 | ||
ac63149c WP |
27 | We hang out in the |
28 | [`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on | |
29 | irc.freenode.net. | |
41b00ccc | 30 | |
1631147c RB |
31 | Also, feel free to open an |
32 | [Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion | |
33 | about any concerns you have. We like to use Issues for that so there is an | |
34 | easily accessible permanent record of the conversation. | |
35 | ||
a142ed91 RB |
36 | ## Libgit2 Versions |
37 | ||
c25aa7cd | 38 | The `main` branch is the main branch where development happens. |
a142ed91 | 39 | Releases are tagged |
b247a39d | 40 | (e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0) ) |
a142ed91 RB |
41 | and when a critical bug fix needs to be backported, it will be done on a |
42 | `<tag>-maint` maintenance branch. | |
43 | ||
41b00ccc BS |
44 | ## Reporting Bugs |
45 | ||
1631147c RB |
46 | First, know which version of libgit2 your problem is in and include it in |
47 | your bug report. This can either be a tag (e.g. | |
ac63149c WP |
48 | [v0.17.0](https://github.com/libgit2/libgit2/releases/tag/v0.17.0)) or a |
49 | commit SHA | |
50 | (e.g. [01be7863](https://github.com/libgit2/libgit2/commit/01be7863)). | |
51 | Using [`git describe`](http://git-scm.com/docs/git-describe) is a | |
a142ed91 | 52 | great way to tell us what version you're working with. |
1631147c | 53 | |
c25aa7cd | 54 | If you're not running against the latest `main` branch version, |
1631147c RB |
55 | please compile and test against that to avoid re-reporting an issue that's |
56 | already been fixed. | |
41b00ccc | 57 | |
1631147c RB |
58 | It's *incredibly* helpful to be able to reproduce the problem. Please |
59 | include a list of steps, a bit of code, and/or a zipped repository (if | |
60 | possible). Note that some of the libgit2 developers are employees of | |
61 | GitHub, so if your repository is private, find us on IRC and we'll figure | |
62 | out a way to help you. | |
41b00ccc BS |
63 | |
64 | ## Pull Requests | |
65 | ||
09846fd1 ET |
66 | Our work flow is a [typical GitHub |
67 | flow](https://guides.github.com/introduction/flow/index.html), where | |
68 | contributors fork the [libgit2 repository](https://github.com/libgit2/libgit2), | |
a142ed91 | 69 | make their changes on branch, and submit a |
09846fd1 | 70 | [Pull Request](https://help.github.com/articles/using-pull-requests) |
c25aa7cd | 71 | (a.k.a. "PR"). Pull requests should usually be targeted at the `main` |
09846fd1 | 72 | branch. |
41b00ccc | 73 | |
1631147c | 74 | Life will be a lot easier for you (and us) if you follow this pattern |
c25aa7cd | 75 | (i.e. fork, named branch, submit PR). If you use your fork's `main` |
a142ed91 RB |
76 | branch directly, things can get messy. |
77 | ||
78 | Please include a nice description of your changes when you submit your PR; | |
79 | if we have to read the whole diff to figure out why you're contributing | |
80 | in the first place, you're less likely to get feedback and have your change | |
81 | merged in. | |
82 | ||
eae0bfdc PP |
83 | In addition to outlining your thought process in the PR's description, please |
84 | also try to document it in your commits. We welcome it if every commit has a | |
85 | description of why you have been doing your changes alongside with your | |
86 | reasoning why this is a good idea. The messages shall be written in | |
87 | present-tense and in an imperative style (e.g. "Add feature foobar", not "Added | |
88 | feature foobar" or "Adding feature foobar"). Lines should be wrapped at 80 | |
89 | characters so people with small screens are able to read the commit messages in | |
90 | their terminal without any problem. | |
91 | ||
92 | To make it easier to attribute commits to certain parts of our code base, we | |
93 | also prefer to have the commit subject be prefixed with a "scope". E.g. if you | |
94 | are changing code in our merging subsystem, make sure to prefix the subject with | |
95 | "merge:". The first word following the colon shall start with an lowercase | |
96 | letter. The maximum line length for the subject is 70 characters, preferably | |
97 | shorter. | |
98 | ||
a142ed91 RB |
99 | If you are starting to work on a particular area, feel free to submit a PR |
100 | that highlights your work in progress (and note in the PR title that it's | |
101 | not ready to merge). These early PRs are welcome and will help in getting | |
102 | visibility for your fix, allow others to comment early on the changes and | |
103 | also let others know that you are currently working on something. | |
1631147c | 104 | |
a142ed91 | 105 | Before wrapping up a PR, you should be sure to: |
41b00ccc | 106 | |
09846fd1 | 107 | * Write tests to cover any functional changes |
a142ed91 | 108 | * Update documentation for any changed public APIs |
ac3d33df | 109 | * Add to the [`changelog.md`](changelog.md) file describing any major changes |
6ca83665 | 110 | |
09846fd1 ET |
111 | ## Unit Tests |
112 | ||
113 | We believe that our unit tests allow us to keep the quality of libgit2 | |
114 | high: any new changes must not cause unit test failures, and new changes | |
115 | should include unit tests that cover the bug fixes or new features. | |
116 | For bug fixes, we prefer unit tests that illustrate the failure before | |
117 | the change, but pass with your changes. | |
118 | ||
119 | In addition to new tests, please ensure that your changes do not cause | |
120 | any other test failures. Running the entire test suite is helpful | |
121 | before you submit a pull request. When you build libgit2, the test | |
1308059d | 122 | suite will also be built. You can run most of the tests by simply running |
09846fd1 ET |
123 | the resultant `libgit2_clar` binary. If you want to run a specific |
124 | unit test, you can name it with the `-s` option. For example: | |
125 | ||
126 | libgit2_clar -sstatus::worktree::long_filenames | |
127 | ||
128 | Or you can run an entire class of tests. For example, to run all the | |
129 | worktree status tests: | |
130 | ||
131 | libgit2_clar -sstatus::worktree | |
132 | ||
1308059d ET |
133 | The default test run is fairly exhaustive, but it will exclude some |
134 | unit tests by default: in particular, those that talk to network | |
135 | servers and the tests that manipulate the filesystem in onerous | |
136 | ways (and may need to have special privileges to run). To run the | |
137 | network tests: | |
138 | ||
139 | libgit2_clar -ionline | |
140 | ||
141 | In addition, various tests may be enabled by environment variables, | |
142 | like the ones that write exceptionally large repositories or manipulate | |
143 | the filesystem structure in unexpected ways. These tests *may be | |
144 | dangerous* to run on a normal machine and may harm your filesystem. It's | |
145 | not recommended that you run these; instead, the continuous integration | |
146 | servers will run these (in a sandbox). | |
147 | ||
41b00ccc BS |
148 | ## Porting Code From Other Open-Source Projects |
149 | ||
1631147c RB |
150 | `libgit2` is licensed under the terms of the GPL v2 with a linking |
151 | exception. Any code brought in must be compatible with those terms. | |
152 | ||
153 | The most common case is porting code from core Git. Git is a pure GPL | |
154 | project, which means that in order to port code to this project, we need the | |
155 | explicit permission of the author. Check the | |
41b00ccc | 156 | [`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors) |
6ca83665 | 157 | file for authors who have already consented. |
41b00ccc | 158 | |
1631147c RB |
159 | Other licenses have other requirements; check the license of the library |
160 | you're porting code *from* to see what you need to do. As a general rule, | |
161 | MIT and BSD (3-clause) licenses are typically no problem. Apache 2.0 | |
162 | license typically doesn't work due to GPL incompatibility. | |
41b00ccc | 163 | |
a142ed91 RB |
164 | If your pull request uses code from core Git, another project, or code |
165 | from a forum / Stack Overflow, then *please* flag this in your PR and make | |
166 | sure you've given proper credit to the original author in the code | |
167 | snippet. | |
6ca83665 | 168 | |
1631147c | 169 | ## Style Guide |
41b00ccc | 170 | |
68a19ca9 RB |
171 | The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C) |
172 | (a.k.a. C89) compatible. Internally, `libgit2` is written using a portable | |
72556cc6 | 173 | subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep |
68a19ca9 RB |
174 | local variable declarations at the tops of blocks only and avoid `//` style |
175 | comments. Additionally, `libgit2` follows some extra conventions for | |
176 | function and type naming, code formatting, and testing. | |
1631147c RB |
177 | |
178 | We like to keep the source code consistent and easy to read. Maintaining | |
179 | this takes some discipline, but it's been more than worth it. Take a look | |
ac3d33df | 180 | at the [conventions file](conventions.md). |
41b00ccc | 181 | |
1631147c RB |
182 | ## Starter Projects |
183 | ||
ac3d33df | 184 | See our [projects list](projects.md). |