diff options
| -rw-r--r-- | CONTRIBUTING.md | 21 | ||||
| -rw-r--r-- | PROJECTS.md | 88 | ||||
| -rw-r--r-- | README.md | 25 |
3 files changed, 103 insertions, 31 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06aa4c1dd..4efe28ed3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -101,23 +101,4 @@ at the ## 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: - -* Look at the `examples/` programs, find an existing one that mirrors a - core Git command and add a missing command-line option. There are many - gaps right now and this helps demonstrate how to use the library. -* Pick a Git command that is not emulates in `examples/` and write a new - example that mirrors the behavior. Examples don't have to be perfect - emulations, but should demonstrate how to use the libgit2 APIs to get - results that are similar to Git commands. 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. +See our [projects list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md). diff --git a/PROJECTS.md b/PROJECTS.md new file mode 100644 index 000000000..34ba18ace --- /dev/null +++ b/PROJECTS.md @@ -0,0 +1,88 @@ +Projects For LibGit2 +==================== + +So, you want to start helping out with `libgit2`? That's fantastic! We +welcome contributions and we promise we'll try to be nice. + +This is a list of libgit2 related projects that new contributors can take +on. It includes a number of good starter projects and well as some larger +ideas that no one is actively working on. + +## Before You Start + +Please start by reading the README.md, CONTRIBUTING.md, and CONVENTIONS.md +files before diving into one of these projects. Those will explain our +work flow and coding conventions to help ensure that your work will be +easily integrated into libgit2. + +Next, work through the build instructions and make sure you can clone the +repository, compile it, and run the tests successfully. That will make +sure that your development environment is set up correctly and you are +ready to start on libgit2 development. + +## Starter Projects + +These are good small projects to get started with libgit2. + +* Look at the `examples/` programs, find an existing one that mirrors a + core Git command and add a missing command-line option. There are many + gaps right now and this helps demonstrate how to use the library. Here + are some specific ideas: + * Add the `--minimal` flag to `examples/diff.c` since the `libgit2` + diff API now has a flag to support it + * Add the `--patience` flag to `examples/diff.c` since it is also now + supported. + * Add the `--shortstat` flag to `examples/diff.c` based on the work + that was done to add `--numstat` already. + * Fix the `examples/diff.c` implementation of the `-B` + (a.k.a. `--break-rewrites`) command line option to actually look for + the optional `[<n>][/<m>]` configuration values. There is an + existing comment that reads `/* TODO: parse thresholds */`. The + trick to this one will be doing it in a manner that is clean and + simple, but still handles the various cases correctly (e.g. `-B/70%` + is apparently a legal setting). + * Implement the `--log-size` option for `examples/log.c`. I think all + the data is available, you would just need to add the code into the + `print_commit()` routine (along with a way of passing the option + into that function). + * For `examples/log.c`, implement any one of `--author=<...>`, + `--committer=<...>`, or `--grep=<...>` but just use simple string + match with `strstr()` instead of full regular expression + matching. (I.e. I'm suggesting implementing this as if + `--fixed-strings` was always turned on, because it will be a simpler + project.) + * As an extension to the matching idea for `examples/log.c`, add the + `-i` option to use `strcasestr()` for matches. + * For `examples/log.c`, implement the `--first-parent` option now that + libgit2 supports it in the revwalk API. +* Pick a Git command that is not already emulated in `examples/` and write + a new example that mirrors the behavior. Examples don't have to be + perfect emulations, but should demonstrate how to use the libgit2 APIs + to get results that are similar to Git commands. 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. + +If none of these appeal to you, take a look at our issues list to see if +there are any unresolved issues you'd like to jump in on. + +## Larger Projects + +These are ideas for larger projects mostly taken from our backlog of +[Issues](https://github.com/libgit2/libgit2/issues). Please don't dive +into one of these as a first project for libgit2 - we'd rather get to +know you first by successfully shipping your work on one of the smaller +projects above. + +* Port part of the Git test suite to run against the command line emulation + in examples/ +* Fix symlink support for files in the .git directory (i.e. don't overwrite + the symlinks when writing the file contents back out) +* Implement a 'git describe' like API +* Add hooks API to enumerate and manage hooks (not run them at this point) +* Isolate logic of ignore evaluation into a standalone API +* Upgrade internal libxdiff code to latest from core Git +* Add a hashtable lookup for files in the index instead of binary search + every time @@ -4,9 +4,9 @@ libgit2 - the Git linkable library [](http://travis-ci.org/libgit2/libgit2) [](https://scan.coverity.com/projects/639) -`libgit2` is a portable, pure C implementation of the Git core methods provided as a -re-entrant linkable library with a solid API, allowing you to write native -speed custom Git applications in any language with bindings. +`libgit2` is a portable, pure C implementation of the Git core methods +provided as a re-entrant linkable library with a solid API, allowing you to +write native speed custom Git applications in any language with bindings. `libgit2` is licensed under a **very permissive license** (GPLv2 with a special Linking Exception). This basically means that you can link it (unmodified) @@ -30,8 +30,9 @@ Additionally, the example code has been released to the public domain (see the What It Can Do ============== -`libgit2` is already very usable and is being used in production for many applications including the GitHub.com site, in Plastic SCM -and also powering Microsoft's Visual Studio tools for Git. The library provides: +`libgit2` is already very usable and is being used in production for many +applications including the GitHub.com site, in Plastic SCM and also powering +Microsoft's Visual Studio tools for Git. The library provides: * SHA conversions, formatting and shortening * abstracted ODB backend system @@ -199,14 +200,16 @@ we can add it to the list. How Can I Contribute? ================================== -Check the [contribution guidelines](CONTRIBUTING.md). - +Check the [contribution guidelines](CONTRIBUTING.md) to understand our +workflow, the libgit2 [coding conventions](CONVENTIONS.md), and out list of +[good starting projects](PROJECTS.md). License ================================== -`libgit2` is under GPL2 **with linking exemption**. This means you -can link to and use the library from any program, proprietary or open source; paid -or gratis. However, you cannot modify libgit2 and distribute it without + +`libgit2` is under GPL2 **with linking exemption**. This means you can link to +and use the library from any program, proprietary or open source; paid or +gratis. However, you cannot modify libgit2 and distribute it without supplying the source. -See the COPYING file for the full license text. +See the [COPYING file](COPYING) for the full license text. |