]>
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 | ||
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 |
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 |
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) |
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 |
141 | file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md). | |
41b00ccc | 142 | |
1631147c RB |
143 | ## Starter Projects |
144 | ||
09846fd1 ET |
145 | See our [projects |
146 | list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md). |