diff options
| -rw-r--r-- | CONTRIBUTING.md | 64 | ||||
| -rw-r--r-- | PROJECTS.md | 44 |
2 files changed, 75 insertions, 33 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4efe28ed3..1444596d2 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/PROJECTS.md b/PROJECTS.md index d17214471..5164d95b6 100644 --- a/PROJECTS.md +++ b/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") |