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` 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.
  15
  16 ## Discussion & Chat
  17
  18 We hang out in the
  19 [`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
  20 irc.freenode.net.
  21
  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
  27 ## Libgit2 Versions
  28
  29 The `master` branch is the main branch where development happens.
  30 Releases are tagged
  31 (e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0) )
  32 and when a critical bug fix needs to be backported, it will be done on a
  33 `<tag>-maint` maintenance branch.
  34
  35 ## Reporting Bugs
  36
  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.
  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
  43 great way to tell us what version you're working with.
  44
  45 If you're not running against the latest `master` branch version,
  46 please compile and test against that to avoid re-reporting an issue that's
  47 already been fixed.
  48
  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.
  54
  55 ## Pull Requests
  56
  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),
  60 make their changes on branch, and submit a
  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.
  64
  65 Life will be a lot easier for you (and us) if you follow this pattern
  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.
  79
  80 Before wrapping up a PR, you should be sure to:
  81
  82 * Write tests to cover any functional changes
  83 * Update documentation for any changed public APIs
  84 * Add to the [`CHANGELOG.md`](CHANGELOG.md) file describing any major changes
  85
  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 most of the 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
 108 The default test run is fairly exhaustive, but it will exclude some
 109 unit tests by default: in particular, those that talk to network
 110 servers and the tests that manipulate the filesystem in onerous
 111 ways (and may need to have special privileges to run).  To run the
 112 network tests:
 113
 114     libgit2_clar -ionline
 115
 116 In addition, various tests may be enabled by environment variables,
 117 like the ones that write exceptionally large repositories or manipulate
 118 the filesystem structure in unexpected ways.  These tests *may be
 119 dangerous* to run on a normal machine and may harm your filesystem.  It's
 120 not recommended that you run these; instead, the continuous integration
 121 servers will run these (in a sandbox).
 122
 123 ## Porting Code From Other Open-Source Projects
 124
 125 `libgit2` is licensed under the terms of the GPL v2 with a linking
 126 exception.  Any code brought in must be compatible with those terms.
 127
 128 The most common case is porting code from core Git.  Git is a pure GPL
 129 project, which means that in order to port code to this project, we need the
 130 explicit permission of the author.  Check the
 131 [`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
 132 file for authors who have already consented.
 133
 134 Other licenses have other requirements; check the license of the library
 135 you're porting code *from* to see what you need to do.  As a general rule,
 136 MIT and BSD (3-clause) licenses are typically no problem.  Apache 2.0
 137 license typically doesn't work due to GPL incompatibility.
 138
 139 If your pull request uses code from core Git, another project, or code
 140 from a forum / Stack Overflow, then *please* flag this in your PR and make
 141 sure you've given proper credit to the original author in the code
 142 snippet.
 143
 144 ## Style Guide
 145
 146 The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
 147 (a.k.a. C89) compatible.  Internally, `libgit2` is written using a portable
 148 subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep
 149 local variable declarations at the tops of blocks only and avoid `//` style
 150 comments.  Additionally, `libgit2` follows some extra conventions for
 151 function and type naming, code formatting, and testing.
 152
 153 We like to keep the source code consistent and easy to read.  Maintaining
 154 this takes some discipline, but it's been more than worth it.  Take a look
 155 at the [conventions
 156 file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
 157
 158 ## Starter Projects
 159
 160 See our [projects
 161 list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).