diff options
author | Russell Belfer <rb@github.com> | 2013-03-02 13:51:31 -0800 |
---|---|---|
committer | Russell Belfer <rb@github.com> | 2013-03-02 13:51:31 -0800 |
commit | 1631147c196ff32a82f8775e3979fdf42729de6b (patch) | |
tree | a5cdd6e6a79eebc569e9dfcbd98d3992fdee77ba /CONTRIBUTING.md | |
parent | 01be786319238fd6507a08316d1c265c1a89407f (diff) | |
download | libgit2-1631147c196ff32a82f8775e3979fdf42729de6b.tar.gz |
Updates to CONTRIBUTING and CONVENTIONS
The discussion about converting some of our foreach-style APIs to
use iterator objects got me wanting to make a list of good starter
projects. I put it in CONTRIBUTING.md and then went crazy with
updates to that file and to CONVENTIONS.md.
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r-- | CONTRIBUTING.md | 97 |
1 files changed, 75 insertions, 22 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 856179481..04a537f97 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,41 +7,94 @@ your help. We hang out in the #libgit2 channel on irc.freenode.net. +Also, feel free to open an +[Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion +about any concerns you have. We like to use Issues for that so there is an +easily accessible permanent record of the conversation. + ## Reporting Bugs -First, know which version of libgit2 your problem is in. Compile and test -against the `development` branch to avoid re-reporting an issue that's already -been fixed. +First, know which version of libgit2 your problem is in and include it in +your bug report. This can either be a tag (e.g. +[v0.17.0](https://github.com/libgit2/libgit2/tree/v0.17.0) ) or a commit +SHA (e.g. +[01be7863](https://github.com/libgit2/libgit2/commit/01be786319238fd6507a08316d1c265c1a89407f) +). Using [`git describe`](http://git-scm.com/docs/git-describe) is a great +way to tell us what version you're working with. + +If you're not running against the latest `development` branch version, +please compile and test against that to avoid re-reporting an issue that's +already been fixed. -It's *incredibly* helpful to be able to reproduce the problem. Please include -a bit of code and/or a zipped repository (if possible). Note that some of the -developers are employees of GitHub, so if your repository is private, find us -on IRC and we'll figure out a way to help you. +It's *incredibly* helpful to be able to reproduce the problem. Please +include a list of steps, a bit of code, and/or a zipped repository (if +possible). Note that some of the libgit2 developers are employees of +GitHub, so if your repository is private, find us on IRC and we'll figure +out a way to help you. ## Pull Requests -Life will be a lot easier for you if you create a named branch for your -contribution, rather than just using your fork's `development`. +Our work flow is a typical GitHub flow, where contributors fork the +[libgit2 repository](https://github.com/libgit2/libgit2), make their changes +on branch, and submit a +[Pull Request](https://help.github.com/articles/using-pull-requests) +(a.k.a. "PR"). -It's helpful if you include a nice description of your change with your PR; if -someone has to read the whole diff to figure out why you're contributing in the -first place, you're less likely to get feedback and have your change merged in. +Life will be a lot easier for you (and us) if you follow this pattern +(i.e. fork, named branch, submit PR). If you use your fork's `development` +branch, things can get messy. + +Please include a nice description of your changes with your PR; if we have +to read the whole diff to figure out why you're contributing in the first +place, you're less likely to get feedback and have your change merged in. ## Porting Code From Other Open-Source Projects -The most common case here is porting code from core Git. Git is a GPL project, -which means that in order to port code to this project, we need the explicit -permission of the author. Check the +`libgit2` is licensed under the terms of the GPL v2 with a linking +exception. Any code brought in must be compatible with those terms. + +The most common case is porting code from core Git. Git is a pure GPL +project, which means that in order to port code to this project, we need the +explicit permission of the author. Check the [`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors) -file for authors who have already consented; feel free to add someone if you've -obtained their consent. +file for authors who have already consented; feel free to add someone if +you've obtained their consent. -Other licenses have other requirements; check the license of the library you're -porting code *from* to see what you need to do. +Other licenses have other requirements; check the license of the library +you're porting code *from* to see what you need to do. As a general rule, +MIT and BSD (3-clause) licenses are typically no problem. Apache 2.0 +license typically doesn't work due to GPL incompatibility. -## Styleguide +## Style Guide -We like to keep the source code consistent and easy to read. Maintaining this -takes some discipline, but it's been more than worth it. Take a look at the +`libgit2` is written in [ANSI C](http://en.wikipedia.org/wiki/ANSI_C) +(a.k.a. C89) with some specific conventions for function and type naming, +code formatting, and testing. + +We like to keep the source code consistent and easy to read. Maintaining +this takes some discipline, but it's been more than worth it. Take a look +at the [conventions file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md). +## Starter Projects + +So, you want to start helping out with `libgit2`? That's fantastic? We +welcome contributions and we promise we'll try to be nice. + +If you want to jump in, you can look at our issues list to see if there +are any unresolved issues to jump in on. Also, here is a list of some +smaller project ideas that could help you become familiar with the code +base and make a nice first step: + +* Convert a `git_*modulename*_foreach()` callback-based iteration API + into a `git_*modulename*_iterator` object with a create/advance style + of API. This helps folks writing language bindings and usually isn't + too complicated. +* Write a new `examples/` program that mirrors a particular core git + command. (See `examples/diff.c` for example.) This lets you (and us) + easily exercise a particular facet of the API and measure compatability + and feature parity with core git. +* Submit a PR to clarify documentation! While we do try to document all of + the APIs, your fresh eyes on the documentation will find areas that are + confusing much more easily. + |