Update CONTRIBUTING and PROJECTS

This updates CONTRIBUTING to reflect the changes to use the
master branch and make explicit recommendations about updating
CHANGELOG.md and providing test coverage.  Also, this includes
some old updates to PROJECTS.md that I wrote to expand the list
of projects, pulling in things from old feature requests.

CONTRIBUTING.md

@@ -22,17 +22,25 @@ Also, feel free to open an
 about any concerns you have.  We like to use Issues for that so there is an
 easily accessible permanent record of the conversation.
 
+## Libgit2 Versions
+
+The `master` branch is the main branch where development happens.
+Releases are tagged
+(e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0)
+and when a critical bug fix needs to be backported, it will be done on a
+`<tag>-maint` maintenance branch.
+
 ## Reporting Bugs
 
 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.
+[v0.17.0](https://github.com/libgit2/libgit2/releases/tag/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.
+).  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,
+If you're not running against the latest `master` branch version,
 please compile and test against that to avoid re-reporting an issue that's
 already been fixed.
 
@@ -44,25 +52,33 @@ out a way to help you.
 
 ## Pull Requests
 
-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").
+Our work flow is a [typical GitHub flow](https://guides.github.com/introduction/flow/index.html),
+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").
+Pull requests should usually be targeted at the `master` branch.
 
 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.
+(i.e. fork, named branch, submit PR).  If you use your fork's `master`
+branch directly, things can get messy.
+
+Please include a nice description of your changes when you submit 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.
+
+If you are starting to work on a particular area, feel free to submit a PR
+that highlights your work in progress (and note in the PR title that it's
+not ready to merge). These early PRs are welcome and will help in getting
+visibility for your fix, allow others to comment early on the changes and
+also let others know that you are currently working on something.
 
-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.
+Before wrapping up a PR, you should be sure to:
 
-If you are working on a particular area then feel free to submit a PR that
-highlights your work in progress (and flag in the PR title that it's not
-ready to merge). This will help in getting visibility for your fix, allow
-others to comment early on the changes and also let others know that you
-are currently working on something.
+* Write tests to cover any functional changes (ideally tests that would
+  have failed before the PR and now pass)
+* Update documentation for any changed public APIs
+* Add to the [`CHANGELOG.md`](CHANGELOG.md) file describing any major changes
 
 ## Porting Code From Other Open-Source Projects
 
@@ -80,10 +96,10 @@ 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.
 
-If you are pulling in code from core Git, another project or code you've
-pulled from a forum / Stack Overflow then please flag this in your PR and
-also make sure you've given proper credit to the original author in the
-code snippet.
+If your pull request uses code from core Git, another project, or code
+from a forum / Stack Overflow, then *please* flag this in your PR and make
+sure you've given proper credit to the original author in the code
+snippet.
 
 ## Style Guide
 

PROJECTS.md

@@ -10,10 +10,11 @@ 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.
+Please start by reading the [README.md](README.md),
+[CONTRIBUTING.md](CONTRIBUTING.md), and [CONVENTIONS.md](CONVENTIONS.md)
+files before diving into one of these projects.  Those 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
@@ -27,7 +28,7 @@ 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:
+  are some specific ideas (though there are many more):
     * 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
@@ -67,19 +68,44 @@ 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.
 
+Some of these projects are broken down into subprojects and/or have
+some incremental steps listed towards the larger goal.  Those steps
+might make good smaller projects by themselves.
+
 * Port part of the Git test suite to run against the command line emulation
   in examples/
+    * Pick a Git command that is emulated in our examples/ area
+    * Extract the Git tests that exercise that command
+    * Convert the tests to call our emulation
+    * These tests could go in examples/tests/...
 * 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)
+    * Enumeration of available hooks
+    * Lookup API to see which hooks have a script and get the script
+    * Read/write API to load a hook script and write a hook script
+    * Eventually, callback API to invoke a hook callback when libgit2
+      executes the action in question
 * 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
+* Improve index internals with hashtable lookup for files instead of
+  using binary search every time
 * Make the index write the cache out to disk (with tests to gain
   confidence that the caching invalidation works correctly)
-* Have the tree builder use a hash table when building instead of a
-  list.
+* Tree builder improvements:
+    * Use a hash table when building instead of a list
+    * Extend to allow building a tree hierarchy
 * Move the tagopt mechanism to the newer git 1.9 interpretation of
   --tags [#2120](https://github.com/libgit2/libgit2/issues/2120)
+* Apply-patch API
+* Add a patch editing API to enable "git add -p" type operations
+* Textconv API to filter binary data before generating diffs (something
+  like the current Filter API, probably).
+* Performance profiling and improvement
+* Build in handling of "empty tree" and "empty blob" SHAs
+* Support "git replace" ref replacements
+* Include conflicts in diff results and in status
+    * GIT_DELTA_CONFLICT for items in conflict (with multiple files)
+    * Appropriate flags for status
+* Support sparse checkout (i.e. "core.sparsecheckout" and ".git/info/sparse-checkout")