Merge pull request #2143 from libgit2/rb/projects

Add project list and update readme

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).

PROJECTS.md

+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

README.md

@@ -4,9 +4,9 @@ libgit2 - the Git linkable library
 [![Build Status](https://secure.travis-ci.org/libgit2/libgit2.png?branch=development)](http://travis-ci.org/libgit2/libgit2)
 [![Coverity Scan Build Status](https://scan.coverity.com/projects/639/badge.svg)](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.