Merge pull request #2143 from libgit2/rb/projects Add project list and update readme
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 06aa4c1..4efe28e 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 0000000..34ba18a
--- /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
diff --git a/README.md b/README.md
index aa75bb0..8dd0734 100644
--- a/README.md
+++ b/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.