Merge pull request #2434 from libgit2/rb/contributing-updates

Update CONTRIBUTING and PROJECTS

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