Add deprecation mechanism (introduces runtime dependency on ActiveSupport) (#645)

* Add deprecation mechanism (introduces runtime dependency on ActiveSupport)

Signed-off-by: James Couball <[email protected]>

* Disable YARD doc generation when using TruffleRuby

Signed-off-by: James Couball <[email protected]>

---------

Signed-off-by: James Couball <[email protected]>

Author: jcouball

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
 

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.

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'
 

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'

tests/test_helper.rb

@@ -5,6 +5,8 @@
 
 require "git"
 
+Git.deprecation.behavior = :silence
+
 class Test::Unit::TestCase
 
   TEST_ROOT = File.expand_path(__dir__)

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