From f055fed4c2e22ff3394f3f2d9be8e8095f85dbee Mon Sep 17 00:00:00 2001 From: James Couball Date: Sun, 5 Mar 2023 16:26:50 -0800 Subject: [PATCH 1/2] Add deprecation mechanism (introduces runtime dependency on ActiveSupport) Signed-off-by: James Couball --- README.md | 68 ++++++++++++++++++++--------- git.gemspec | 1 + lib/git.rb | 33 ++++++++++++-- tests/test_helper.rb | 2 + tests/units/test_git_deprecation.rb | 11 +++++ 5 files changed, 90 insertions(+), 25 deletions(-) create mode 100644 tests/units/test_git_deprecation.rb diff --git a/README.md b/README.md index 661fad7a..578cd1c6 100644 --- a/README.md +++ b/README.md @@ -3,47 +3,73 @@ # @title README --> -# The Git Gem +# The `git` Gem -The Git Gem provides an API that can be used to create, read, and manipulate +[![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git) +[![Change Log](https://img.shields.io/badge/change%20log-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md) +[![Build Status](https://github.com/ruby-git/ruby-git/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/ruby-git/ruby-git/actions/workflows/continuous_integration.yml) +[![Code Climate](https://codeclimate.com/github/ruby-git/ruby-git.png)](https://codeclimate.com/github/ruby-git/ruby-git) +[![Source Code](https://img.shields.io/badge/source-GitHub-green)](https://github.com/ruby-git/ruby-git) +[![Documentation](https://img.shields.io/badge/documentation-Latest-green)](https://rubydoc.info/gems/git) +[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ruby-git/ruby-git/blob/master/LICENSE) + +The git Gem provides an API that can be used to create, read, and manipulate Git repositories by wrapping system calls to the `git` binary. The API can be used for working with Git in complex interactions including branching and merging, object inspection and manipulation, history, patch generation and more. -## Homepage +## Basic Usage -The project source code is at: +Get started by obtaining a repository object by: -http://github.com/ruby-git/ruby-git +* Opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method) +* Initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method) +* Cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method) -## Documentation +Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base) -Detailed documentation can be found at: +## Install -https://rubydoc.info/gems/git/Git.html +You can install the `git` gem with the following command: -Get started by obtaining a repository object by: - -* opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method) -* initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method) -* cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method) +```shell +gem install git +``` -Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base) +## Deprecation Warnings -## Install +Deprecation warnings are managed with the `Git.deprecation` attribute. -You can install Ruby/Git like this: +Use this object to define deprecations in the source code: +```ruby +Git.deprecation.deprecate_methods(Git::Branch, stashes: 'use Git::Base#stash_list instead') ``` -sudo gem install git + +The default action when using deprecated items (methods, classes, etc.) is to output +a **DEPRECATION WARNING** to `$stderr` like the following: + +```text +DEPRECATION WARNING: stashes is deprecated and will be removed from git 2.0.0 (use Git::Base.stash_list instead) ``` -## Code Status +The action taken when a deprecated item is used is defined by setting the behavior +on the deprecation object: + +```ruby +# Log all deprecation warnings to $stderr (the default) +Git.deprecation = :stderr + +# Raise an ActiveSupport::DeprecationException +Git.deprecation = :raise + +# Do nothing +Git.deprecation = :silence +``` -* [![Build Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=master)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) -* [![Code Climate](https://codeclimate.com/github/ruby-git/ruby-git.png)](https://codeclimate.com/github/ruby-git/ruby-git) -* [![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git) +See [ActiveSupport::Deprecation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html) +for more details on how to use deprecations. ## Major Objects diff --git a/git.gemspec b/git.gemspec index 50b9c140..42c4298f 100644 --- a/git.gemspec +++ b/git.gemspec @@ -26,6 +26,7 @@ Gem::Specification.new do |s| s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to?(:required_rubygems_version=) s.requirements = ['git 1.6.0.0, or greater'] + s.add_runtime_dependency 'activesupport', '>= 4.0.0' s.add_runtime_dependency 'addressable', '~> 2.8' s.add_runtime_dependency 'rchardet', '~> 1.8' diff --git a/lib/git.rb b/lib/git.rb index 10f25d60..4c2012b9 100644 --- a/lib/git.rb +++ b/lib/git.rb @@ -1,7 +1,32 @@ -# Add the directory containing this file to the start of the load path if it -# isn't there already. -$:.unshift(File.dirname(__FILE__)) unless - $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__))) +require 'active_support/deprecation' + +module Git + # An object used to manage deprecations + # + # A ActiveSupport::Deprecation object used to manage the deprecations scheduled + # to be removed in the next major release of the `git`` gem. + # + # @example Deprecate a method + # Git.deprecation.deprecate_methods(Git::Branch, stashes: 'use Git::Base#stash_list instead') + # + # @example Set the deprecation behavior + # # Log all deprecation warnings to $stderr (the default) + # Git.deprecation.behavior = :stderr + # + # # Raise an ActiveSupport::DeprecationException + # Git.deprecation.behavior = :raise + # + # # Do nothing + # Git.deprecation.behavior = :raise + # + # @see https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html ActiveSupport::Deprecation + # + # @return [ActiveSupport::Deprecation] + # + def self.deprecation + @deprecation ||= ActiveSupport::Deprecation.new('2.0.0', 'git') + end +end require 'git/author' require 'git/base' diff --git a/tests/test_helper.rb b/tests/test_helper.rb index 4b7111de..c496d798 100644 --- a/tests/test_helper.rb +++ b/tests/test_helper.rb @@ -5,6 +5,8 @@ require "git" +Git.deprecation.behavior = :silence + class Test::Unit::TestCase TEST_ROOT = File.expand_path(__dir__) diff --git a/tests/units/test_git_deprecation.rb b/tests/units/test_git_deprecation.rb new file mode 100644 index 00000000..c7673ea3 --- /dev/null +++ b/tests/units/test_git_deprecation.rb @@ -0,0 +1,11 @@ +require 'test_helper' + +class TestGitDeprecation < Test::Unit::TestCase + test 'Git.deprecation should return an ActiveSupport::Deprecation' do + assert(Git.deprecation.is_a?(ActiveSupport::Deprecation)) + end + + test 'Calling Git.deprecation more than once should return the same object' do + assert_equal(Git.deprecation.object_id, Git.deprecation.object_id) + end +end From 2c9db28f860cc00a1f300ed4d112346d95e726a4 Mon Sep 17 00:00:00 2001 From: James Couball Date: Sun, 5 Mar 2023 16:42:16 -0800 Subject: [PATCH 2/2] Disable YARD doc generation when using TruffleRuby Signed-off-by: James Couball --- Rakefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Rakefile b/Rakefile index 8504a180..e2d8ef2a 100644 --- a/Rakefile +++ b/Rakefile @@ -18,7 +18,7 @@ task :test do end default_tasks << :test -unless RUBY_PLATFORM == 'java' +unless RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby' # # YARD documentation for this project can NOT be built with JRuby. # This project uses the redcarpet gem which can not be installed on JRuby.