= Deprecatable

== DESCRIPTION

Deprecatable is a library to help you, as a developer, deprecate your API and be proactive about helping people who use your library find where they need to update.

When using Deprecatable, you mark methods as 'deperecated' and then the users of your API will receive a helpful alert showing the exact line of code where they called the deprecated API, and what they need to do to fix it (although you need to supply this piece of information).

Users will receive, by default, a single alert for each unique location a deprecated API method is invoked. They will also receive a final report detailing all the locations where deprecated APIs were invoked.

The "noisiness" of the alerting and the final report is all configurable, via both code, and environment variables. See Deprecatable::Options.

== SYNOPSIS

class SomeClass extend Deprecatable

def deprecate_me
...
end
deprecate :deprecate_me

end

== REQUIREMENTS

No runtime requirements, other than Ruby itself.

== INSTALL

$ [sudo] gem install deprecatable

== EXAMPLES

All of the examles here are included in the examples/ directory.

=== Alerts

Default alerting. Uses Ruby's 'warn' capability, which sends the output to standard error.

$ ruby -Ilib examples/alert_frequency.rb once > /dev/null DEPRECATION WARNING: A::B#deprecate_me DEPRECATION WARNING: ------------------- DEPRECATION WARNING: DEPRECATION WARNING: * Originally defined at /Users/jeremy/Projects/deprecatable/examples/alert_frequency.rb:24 DEPRECATION WARNING: * This method is to be completely removed DEPRECATION WARNING: * Will be removed in version 4.2 DEPRECATION WARNING: DEPRECATION WARNING: Called from /Users/jeremy/Projects/deprecatable/examples/alert_frequency.rb:89 DEPRECATION WARNING: DEPRECATION WARNING: 87: # Context before 1.1 DEPRECATION WARNING: 88: # Context before 1.2 DEPRECATION WARNING: ---> 89: b.deprecate_me DEPRECATION WARNING: 90: # Context after 1.1 DEPRECATION WARNING: 91: # Context after 1.2 DEPRECATION WARNING: DEPRECATION WARNING: To turn this report off do one of the following: DEPRECATION WARNING: * in your ruby code set Deprecatable.options.alert_frequency = :never DEPRECATION WARNING: * set the environment variable DEPRECATABLE_ALERT_FREQUENCY="never" DEPRECATION WARNING:

Lets try that again and shut off the output

$ DEPRECATABLE_ALERT_FREQUENCY=never ruby -Ilib examples/alert_frequency.rb once > /dev/null $

=== A final report when the process exits.

As a bonus, the 'at_exit' report is valid Markdown.

$ ruby -Ilib examples/at_exit.rb > /dev/null Deprecatable 'at_exit' Report

To turn this report off do one of the following:

in your ruby code set Deprecatable.options.has_at_exit_report = false
set the environment variable DEPRECATABLE_HAS_AT_EXIT_REPORT="false"

`A::B#deprecate_me_2`

Originally defined at /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:24
This method is to be completely removed
Will be removed after 2020-02-20

Called 2 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:64

       62:     # Context before 4.1
       63:     # Context before 4.2
  ---> 64:     b.deprecate_me_2
       65:     # Context after 4.1
       66:     # Context after 4.2

Called 4 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:48

       46:     # Context before 2.1
       47:     # Context before 2.2
  ---> 48:     b.deprecate_me_2
       49:     # Context after 2.1
       50:     # Context after 2.2

`A::B#deprecate_me_1`

Originally defined at /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:19
This method is to be completely removed
Will be removed in version 4.2

Called 4 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:42

       40:     # Context before 1.1
       41:     # Context before 1.2
  ---> 42:     b.deprecate_me_1
       43:     # Context after 1.1
       44:     # Context after 1.2

Called 2 time(s) from /Users/jeremy/Projects/deprecatable/examples/at_exit.rb:58

       56:     # Context before 3.1
       57:     # Context before 3.2
  ---> 58:     b.deprecate_me_1
       59:     # Context after 3.1
       60:     # Context after 3.2

And again, shutting off the output:

$ DEPRECATABLE_HAS_AT_EXIT_REPORT="false" ruby -Ilib examples/at_exit.rb > /dev/null $

== DEVELOPERS

If you would like to contribute to the project, you will need to check out the source from http://github.com/copiousfreetime/deprecatable and then if you are using a system installed ruby:

$ rake newb

If you are using a non-root installed ruby, for instance RVM, then you probably want to run:

$ NOSUDO=true rake newb

This task will install any missing dependencies, run the tests/specs, and generate the RDoc.

== LICENSE

(The ISC LICENSE) - http://www.opensource.org/licenses/ISC

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

deprecatable

Commits

Merge pull request #4 from dchelimsky/typo-in-readme

fix typo in README

small cleanup of Rakefile

publish rdocs to a custom location

use the minitest hoe plugin and fix for running rcov in 1.9

Update the README with example output.

README

$ ruby -Ilib examples/at_exit.rb > /dev/null Deprecatable 'at_exit' Report

`A::B#deprecate_me_2`

`A::B#deprecate_me_1`