diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 64 |
1 files changed, 40 insertions, 24 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4efe28ed3..8ebb99154 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 |