diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b97cdca..c81ffb26 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,68 +1,118 @@ # Contributing to ruby-git -Thank you for your interest in contributing to this project. +Thank you for your interest in contributing to the ruby-git project. -These are mostly guidelines, not rules. -Use your best judgment, and feel free to propose changes to this document in a pull request. +This document gives the guidelines for contributing to the ruby-git project. +These guidelines may not fit every situation. When contributing use your best +judgement. -#### Table Of Contents +Propose changes to these guidelines with a pull request. -[How Can I Contribute?](#how-can-i-contribute) - * [Submitting Issues](#submitting-issues) - * [Contribution Process](#contribution-process) - * [Pull Request Requirements](#pull-request-requirements) - * [Code Review Process](#code-review-process) - * [Developer Certification of Origin (DCO)](#developer-certification-of-origin-dco) +## How to contribute to ruby-git +You can contribute in two ways: -## How Can I Contribute? +1. [Report an issue or make a feature request](#how-to-report-an-issue-or-make-a-feature-request) +2. [Submit a code or documentation change](#how-to-submit-a-code-or-documentation-change) -### Submitting Issues +## How to report an issue or make a feature request -We utilize **GitHub Issues** for issue tracking and contributions. You can contribute in two ways: +ruby-git utilizes [GitHub Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues) +for issue tracking and feature requests. -1. Reporting an issue or making a feature request [here](https://github.com/ruby-git/ruby-git/issues/new). -2. Adding features or fixing bugs yourself and contributing your code to ruby-git. +Report an issue or feature request by [creating a ruby-git Github issue](https://github.com/ruby-git/ruby-git/issues/new). +Fill in the template to describe the issue or feature request the best you can. -### Contribution Process +## How to submit a code or documentation change -We have a 3 step process for contributions: +There is three step process for code or documentation changes: -1. Commit changes to a git branch in your fork. Making sure to sign-off those changes for the [Developer Certificate of Origin](#developer-certification-of-origin-dco). -2. Create a GitHub Pull Request for your change, following the instructions in the pull request template. -3. Perform a [Code Review](#code-review-process) with the project maintainers on the pull request. +1. [Commit your changes to a fork of ruby-git](#commit-changes-to-a-fork-of-ruby-git) +2. [Create a pull request](#create-a-pull-request) +3. [Get your pull request reviewed](#get-your-pull-request-reviewed) -### Pull Request Requirements -In order to ensure high quality, we require that all pull requests to this project meet these specifications: +### Commit changes to a fork of ruby-git -1. Unit Testing: We require all the new code to include unit tests, and any fixes to pass previous units. -2. Green CI Tests: We are using [Travis CI](https://travis-ci.org/ruby-git/ruby-git) to run unit tests on various ruby versions, we expect them to all pass before a pull request will be merged. -3. Up-to-date Documentation: New methods as well as updated methods should have [YARD](https://yardoc.org/) documentation added to them +Make your changes in a fork of the ruby-git repository. -### Code Review Process +Each commit must include a [DCO sign-off](#developer-certificate-of-origin-dco) +by adding the line `Signed-off-by: Name ` to the end of the commit +message. -Code review takes place in GitHub pull requests. See [this article](https://help.github.com/articles/about-pull-requests/) if you're not familiar with GitHub Pull Requests. +### Create a pull request -Once you open a pull request, project maintainers will review your code and respond to your pull request with any feedback they might have. +See [this article](https://help.github.com/articles/about-pull-requests/) if you +are not familiar with GitHub Pull Requests. -The process at this point is as follows: +Follow the instructions in the pull request template. -1. One thumbs-up (:+1:) is required from project maintainers. See the master maintainers document for the ruby-git project at . -2. When ready, your pull request will be merged into `master`, we may require you to rebase your PR to the latest `master`. +### Get your pull request reviewed -### Developer Certification of Origin (DCO) +Code review takes place in a GitHub pull request using the [the Github pull request review feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews). -Licensing is very important to open source projects. It helps ensure the software continues to be available under the terms that the author desired. +Once your pull request is ready for review, request a review from at least one +[maintainer](MAINTAINERS.md) and any number of other contributors. -ruby-git uses [the MIT license](https://github.com/ruby-git/ruby-git/blob/master/LICENSE) +During the review process, you may need to make additional commits which would +need to be squashed. It may also be necessary to rebase to master again if other +changes are merged before your PR. -Detail about the LICENSE can be found [here](https://choosealicense.com/licenses/mit/) +At least one approval is required from a project maintainer before your pull +request can be merged. The maintainer is responsible for ensuring that the pull +request meets [the project's coding standards](#coding-standards). -To make a good faith effort to ensure these criteria are met, ruby-git requires the Developer Certificate of Origin (DCO) process to be followed. +## Coding standards -The DCO is an attestation attached to every contribution made by every developer. +In order to ensure high quality, all pull requests must meet these requirements: -In the commit message of the contribution, the developer simply adds a Signed-off-by statement and thereby agrees to the DCO, which you can find below or at . +### 1 PR = 1 Commit + * All commits for a PR must be squashed into one commit + * To avoid an extra merge commit, the PR must be able to be merged as [a fast forward merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) + * The easiest way to ensure a fast forward merge is to rebase your local branch + to the ruby-git master branch + +### Unit tests + * All changes must be accompanied by new or modified unit tests + * The entire test suite must pass when `bundle exec rake test` is run from the + project's local working copy + +### Continuous Integration + * All tests must pass in the project's [Travis CI](https://travis-ci.org/ruby-git/ruby-git) + build before the pull request will be merged + +### Documentation + * New and updated public methods must have [YARD](https://yardoc.org/) + documentation added to them + * New and updated public facing features should be documented in the project's + [README.md](README.md) + +### Licensing sign-off + * Each commit must contain [the DCO sign-off](#developer-certificate-of-origin-dco) + in the form: `Signed-off-by: Name ` + +## Licensing + +ruby-git uses [the MIT license](https://choosealicense.com/licenses/mit/) as +declared in the [LICENSE](LICENSE) file. + +Licensing is very important to open source projects. It helps ensure the +software continues to be available under the terms that the author desired. + +### Developer Certificate of Origin (DCO) + +This project requires that authors have permission to submit their contributions +under the MIT license. To make a good faith effort to ensure this, ruby-git +requires the [Developer Certificate of Origin (DCO)](https://elinux.org/Developer_Certificate_Of_Origin) +process be followed. + +This process requires that each commit include a `Signed-off-by` line that +indicates the author accepts the DCO. Here is an example DCO sign-off line: + +``` +Signed-off-by: John Doe +``` + +The full text of the DCO version 1.1 is below or at . ``` Developer's Certificate of Origin 1.1 @@ -75,7 +125,7 @@ By making a contribution to this project, I certify that: (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open - source license and I have the right under that license to + source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as