Lightning Talk: Deprecatable

by Jeremy Hinegardner

In his lightning talk titled 'Deprecatable' at the Rocky Mountain Ruby 2011 conference, Jeremy Hinegardner discusses the challenges API developers face when needing to deprecate parts of their APIs. He emphasizes the importance of managing API deprecation thoughtfully to ensure that users can smoothly transition to new versions without breaking their existing code.

Key points covered in the talk include:

- The common dilemma for API developers when they need to remove or change API features, which often breaks existing implementations.

- The introduction of a gem called 'deprecate,' developed by Hinegardner, which helps manage deprecation by providing notifications about deprecated methods and their usage.

- Features of the 'deprecate' gem, including:

- Alerts whenever a deprecated method is called, pinpointing the exact location in the code.

- Ability to customize alert frequency through environment variables.

- An exit handler that generates reports on the usage frequency of deprecated methods, which can be output to HTML files.

- Hinegardner showcases an example using the 'deprecate' gem by deprecating a method called 'deprecate_me.' Within this example, he highlights how developers can specify actions for users, such as telling them what to do instead of using the deprecated method.

- He encourages API developers to be considerate towards users and to help them adapt to changes by offering support, as he did with contributions to the Cucumber and Kappa Bear codebases.

- Hinegardner reflects on the development journey of the 'deprecate' gem, mentioning the fun of using Ruby's metaprogramming capabilities and the potential of the gem to be extended by others.

In conclusion, Hinegardner prompts attendees to consider their own API maintenance practices and to adopt tools like the 'deprecate' gem to facilitate smoother transitions for users, reinforcing the value of thoughtful API design.

00:00:03.959 All right. As Anthony eloquently pointed out yesterday, raise your hand if you're an API developer or API designer. Okay, what happens when you want to get rid of an API? You break it. However, as an API developer, you need to make the people who use your API comfortable with removing parts of your code, so someone else can work with it. I had to do this recently; I wrote Launie, which is used by Cucumber and a couple of other projects for launching test case results. I changed the API completely, made two version number changes, and removed two pieces of the API. I wanted to ensure it was easy for everyone to upgrade their code. So I thought, what's the best way to accomplish that?

00:00:45.399 I wrote a gem called 'deprecate.' Let's say you have a piece of code you want to deprecate; that's all you have to do. So, I will bring up some code and demonstrate it. Here, we want to deprecate a method called 'deprecate_me.' The benefit of using 'deprecate' is that it will alert you and provide the exact line of code where the deprecated method was executed.

00:01:10.720 For example, when we call the deprecated method, a warning will appear, indicating the exact line of code that was used to call the deprecated method. Additionally, if you want to change the alert frequency to notify you every time it is called, you can simply adjust it using an environment variable. I also included an exit handler that automatically records every call to the deprecated method. When we call this method multiple times, a report is generated, which can be output to an HTML file listing every call and how many times it was invoked.

00:01:36.200 For instance, we might see that a method was called four times at one location and two times at another. I encourage all of you to maintain your APIs well. Be considerate if you write an API that someone else uses. Because I knew Cucumber and Kappa Bear used my API, I went to their codebases and submitted pull requests to help them update their usage. As a developer of a public API, be kind to your users and assist them in moving forward. If you're changing your code, inform them how to adjust their implementations without causing breakage.

00:02:05.000 So, if you're interested, install the 'deprecate' gem, have fun, and make the most of it! Any questions or comments? I will probably utilize the 'deprecate' gem myself. It's straightforward to extend; you just say 'deprecate' and add a message indicating what users need to do instead. There are various other features, like specifying removal dates and versions.

00:02:57.040 I suspect I'm the only one who uses this gem currently, but it has been a fun and interesting project. It involves Ruby's metaprogramming capabilities, such as opening files, finding the right lines, and printing messages effectively. I’ve enjoyed working on it, and I thought you might find it interesting too. Thank you!