diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a918e2e..78fdc347 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log +## 1.6.0 + +See https://github.com/ruby-git/ruby-git/releases/tag/v1.6.0 + ## 1.6.0.pre1 See https://github.com/ruby-git/ruby-git/releases/tag/v1.6.0.pre1 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 diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 43b76f74..a78a67d6 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,8 +1,9 @@ # Maintainers -When making changes to the system, this file tells you who needs to review your patch - you need at least two maintainers to provide a :+1: on your pull request. +When making changes in this repository, one of the maintainers below must review and approve your pull request. ### Maintainers * [Per Lundberg](https://github.com/perlun) -* [Vern Burton](https://github.com/tarcinil) \ No newline at end of file +* [Vern Burton](https://github.com/tarcinil) +* [James Couball](https://github.com/jcouball) \ No newline at end of file diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000..af99786f --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,57 @@ +# How to release a new git.gem + +Releasing a new version of the `git` gem requires these steps: + * [Prepare the release](#prepare-the-release) + * [Create a GitHub release](#create-a-github-release) + * [Build and release the gem](#build-and-release-the-gem) + +These instructions use an example where the current release version is `1.5.0` +and the new release version to be created is `1.6.0.pre1`. + +## Prepare the release + +From a fork of ruby-git, create a PR containing changes to (1) bump the +version number, (2) update the CHANGELOG.md, and (3) tag the release. + + * Bump the version number in lib/git/version.rb following [Semantic Versioning](https://semver.org) + guidelines + * Add a link in CHANGELOG.md to the release tag which will be created later + in this guide + * Create a new tag using [git-extras](https://github.com/tj/git-extras/blob/master/Commands.md#git-release) + `git release` command + * For example: `git release v1.6.0.pre1` + * These should be the only changes in the PR + * An example of these changes for `v1.6.0.pre1` can be found in [PR #435](https://github.com/ruby-git/ruby-git/pull/435) + * Get the PR reviewed, approved and merged to master. + +## Create a GitHub release + +On [the ruby-git releases page](https://github.com/ruby-git/ruby-git/releases), +select `Draft a new release` + + * Select the tag corresponding to the version being released `v1.6.0.pre1` + * The Target should be `master` + * For the release description, use the output of [changelog-rs](https://github.com/perlun/changelog-rs) + * Since the release has not been created yet, you will need to supply + `changeling-rs` with the current release tag and the tag the new release + is being created from + * For example: `changelog-rs . v1.5.0 v1.6.0.pre1` + * Copy the output, omitting the tag header `## v1.6.0.pre1` and paste into + the release description + * The release description can be edited later if needed + * Select the appropriate value for `This is a pre-release` + * Since `v1.6.0.pre1` is a pre-release, check `This is a pre-release` + +## Build and release the gem + +Clone [ruby-git/ruby-git](https://github.com/ruby-git/ruby-git) directly (not a +fork) and ensure your local working copy is on the master branch + + * Verify that you are not on a fork with the command `git remote -v` + * Verify that the version number is correct by running `rake -T` and inspecting + the output for the `release[remote]` task + +Build the git gem and push it to rubygems.org with the command `rake release` + + * Ensure that your `gem sources list` includes `https://rubygems.org` (in my + case, I usually have my work’s internal gem repository listed) diff --git a/lib/git.rb b/lib/git.rb index 1992dc1d..c0b32b99 100644 --- a/lib/git.rb +++ b/lib/git.rb @@ -19,6 +19,7 @@ require 'git/status' require 'git/stash' require 'git/stashes' +require 'git/version' require 'git/working_directory' lib = Git::Lib.new(nil, nil) @@ -34,7 +35,7 @@ # and more. You should be able to do most fundamental git # operations with this library. # -# This module provides the basic functions to open a git +# This module provides the basic functions to open a git # reference to work with. You can open a working directory, # open a bare repository, initialize a new repo or clone an # existing remote repository. @@ -42,7 +43,7 @@ # Author:: Scott Chacon (mailto:schacon@gmail.com) # License:: MIT License module Git - + #g.config('user.name', 'Scott Chacon') # sets value #g.config('user.email', 'email@email.com') # sets value #g.config('user.name') # returns 'Scott Chacon' @@ -82,7 +83,7 @@ def global_config(name = nil, value = nil) def self.bare(git_dir, options = {}) Base.bare(git_dir, options) end - + # clones a remote repository # # options @@ -110,7 +111,7 @@ def self.export(repository, name, options = {}) repo.checkout("origin/#{options[:branch]}") if options[:branch] Dir.chdir(repo.dir.to_s) { FileUtils.rm_r '.git' } end - + # Same as g.config, but forces it to be at the global level # #g.config('user.name', 'Scott Chacon') # sets value @@ -139,8 +140,8 @@ def self.global_config(name = nil, value = nil) def self.init(working_dir = '.', options = {}) Base.init(working_dir, options) end - - # returns a Hash containing information about the references + + # returns a Hash containing information about the references # of the target repository # # @param [String|NilClass] location the target repository location or nil for '.' @@ -150,7 +151,7 @@ def self.ls_remote(location=nil) end # open an existing git working directory - # + # # this will most likely be the most common way to create # a git reference, referring to a working directory. # if not provided in the options, the library will assume @@ -162,5 +163,5 @@ def self.ls_remote(location=nil) def self.open(working_dir, options = {}) Base.open(working_dir, options) end - + end diff --git a/lib/git/branch.rb b/lib/git/branch.rb index 17573af6..c38c9d4a 100644 --- a/lib/git/branch.rb +++ b/lib/git/branch.rb @@ -37,7 +37,7 @@ def archive(file, opts = {}) # # do other stuff # return true # auto commits and switches back # end - def in_branch (message = 'in branch work') + def in_branch(message = 'in branch work') old_current = @base.lib.branch_current checkout if yield diff --git a/lib/git/version.rb b/lib/git/version.rb index b76d9e69..98430b1f 100644 --- a/lib/git/version.rb +++ b/lib/git/version.rb @@ -1,5 +1,5 @@ module Git # The current gem version # @return [String] the current gem version. - VERSION='1.6.0.pre1' + VERSION='1.6.0' end