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 ## Discussion & Chat
   7
   8 We hang out in the #libgit2 channel on irc.freenode.net.
   9
  10 Also, feel free to open an
  11 [Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion
  12 about any concerns you have.  We like to use Issues for that so there is an
  13 easily accessible permanent record of the conversation.
  14
  15 ## Reporting Bugs
  16
  17 First, know which version of libgit2 your problem is in and include it in
  18 your bug report.  This can either be a tag (e.g.
  19 [v0.17.0](https://github.com/libgit2/libgit2/tree/v0.17.0) ) or a commit
  20 SHA (e.g.
  21 [01be7863](https://github.com/libgit2/libgit2/commit/01be786319238fd6507a08316d1c265c1a89407f)
  22 ).  Using [`git describe`](http://git-scm.com/docs/git-describe) is a great
  23 way to tell us what version you're working with.
  24
  25 If you're not running against the latest `development` branch version,
  26 please compile and test against that to avoid re-reporting an issue that's
  27 already been fixed.
  28
  29 It's *incredibly* helpful to be able to reproduce the problem.  Please
  30 include a list of steps, a bit of code, and/or a zipped repository (if
  31 possible).  Note that some of the libgit2 developers are employees of
  32 GitHub, so if your repository is private, find us on IRC and we'll figure
  33 out a way to help you.
  34
  35 ## Pull Requests
  36
  37 Our work flow is a typical GitHub flow, where contributors fork the
  38 [libgit2 repository](https://github.com/libgit2/libgit2), make their changes
  39 on branch, and submit a
  40 [Pull Request](https://help.github.com/articles/using-pull-requests)
  41 (a.k.a. "PR").
  42
  43 Life will be a lot easier for you (and us) if you follow this pattern
  44 (i.e. fork, named branch, submit PR).  If you use your fork's `development`
  45 branch, things can get messy.
  46
  47 Please include a nice description of your changes with your PR; if we have
  48 to read the whole diff to figure out why you're contributing in the first
  49 place, you're less likely to get feedback and have your change merged in.
  50
  51 If you are working on a particular area then feel free to submit a PR that
  52 highlights your work in progress (and flag in the PR title that it's not
  53 ready to merge). This will help in getting visibility for your fix, allow
  54 others to comment early on the changes and also let others know that you
  55 are currently working on something.
  56
  57 ## Porting Code From Other Open-Source Projects
  58
  59 `libgit2` is licensed under the terms of the GPL v2 with a linking
  60 exception.  Any code brought in must be compatible with those terms.
  61
  62 The most common case is porting code from core Git.  Git is a pure GPL
  63 project, which means that in order to port code to this project, we need the
  64 explicit permission of the author.  Check the
  65 [`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
  66 file for authors who have already consented.
  67
  68 Other licenses have other requirements; check the license of the library
  69 you're porting code *from* to see what you need to do.  As a general rule,
  70 MIT and BSD (3-clause) licenses are typically no problem.  Apache 2.0
  71 license typically doesn't work due to GPL incompatibility.
  72
  73 If you are pulling in code from core Git, another project or code you've pulled from
  74 a forum / Stack Overflow then please flag this in your PR and also make sure you've
  75 given proper credit to the original author in the code snippet.
  76
  77 ## Style Guide
  78
  79 `libgit2` is written in [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
  80 (a.k.a. C89) with some specific conventions for function and type naming,
  81 code formatting, and testing.
  82
  83 We like to keep the source code consistent and easy to read.  Maintaining
  84 this takes some discipline, but it's been more than worth it.  Take a look
  85 at the
  86 [conventions file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
  87
  88 ## Starter Projects
  89
  90 So, you want to start helping out with `libgit2`? That's fantastic? We
  91 welcome contributions and we promise we'll try to be nice.
  92
  93 If you want to jump in, you can look at our issues list to see if there
  94 are any unresolved issues to jump in on.  Also, here is a list of some
  95 smaller project ideas that could help you become familiar with the code
  96 base and make a nice first step:
  97
  98 * Convert a `git_*modulename*_foreach()` callback-based iteration API
  99   into a `git_*modulename*_iterator` object with a create/advance style
 100   of API.  This helps folks writing language bindings and usually isn't
 101   too complicated.
 102 * Write a new `examples/` program that mirrors a particular core git
 103   command.  (See `examples/diff.c` for example.)  This lets you (and us)
 104   easily exercise a particular facet of the API and measure compatability
 105   and feature parity with core git.
 106 * Submit a PR to clarify documentation! While we do try to document all of
 107   the APIs, your fresh eyes on the documentation will find areas that are
 108   confusing much more easily.