docs/contributing.md

   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
   6 ## Licensing
   7
   8 By contributing to libgit2, you agree to release your contribution under
   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).
  12
  13 The `examples` code is governed by the
  14 [CC0 Public Domain Dedication](../examples/COPYING), so that you may copy
  15 from them into your own application.
  16
  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)
  21 - pcre is governed by [BSD license](../deps/pcre/LICENCE)
  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
  25 ## Discussion & Chat
  26
  27 We hang out in the
  28 [`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
  29 irc.freenode.net.
  30
  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
  36 ## Libgit2 Versions
  37
  38 The `main` branch is the main branch where development happens.
  39 Releases are tagged
  40 (e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0) )
  41 and when a critical bug fix needs to be backported, it will be done on a
  42 `<tag>-maint` maintenance branch.
  43
  44 ## Reporting Bugs
  45
  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.
  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
  52 great way to tell us what version you're working with.
  53
  54 If you're not running against the latest `main` branch version,
  55 please compile and test against that to avoid re-reporting an issue that's
  56 already been fixed.
  57
  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.
  63
  64 ## Pull Requests
  65
  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),
  69 make their changes on branch, and submit a
  70 [Pull Request](https://help.github.com/articles/using-pull-requests)
  71 (a.k.a. "PR").  Pull requests should usually be targeted at the `main`
  72 branch.
  73
  74 Life will be a lot easier for you (and us) if you follow this pattern
  75 (i.e. fork, named branch, submit PR).  If you use your fork's `main`
  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
  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
  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.
 104
 105 Before wrapping up a PR, you should be sure to:
 106
 107 * Write tests to cover any functional changes
 108 * Update documentation for any changed public APIs
 109 * Add to the [`changelog.md`](changelog.md) file describing any major changes
 110
 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
 122 suite will also be built.  You can run most of the tests by simply running
 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
 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
 148 ## Porting Code From Other Open-Source Projects
 149
 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
 156 [`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
 157 file for authors who have already consented.
 158
 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.
 163
 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.
 168
 169 ## Style Guide
 170
 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
 173 subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep
 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.
 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
 180 at the [conventions file](conventions.md).
 181
 182 ## Starter Projects
 183
 184 See our [projects list](projects.md).