How to rename a gem?

Question

I have a gem that I want to rename. It is published on RubyGems. I am mostly concerned about people wanting to update it.

I see two paths, but would really like to hear from people who renamed their gem, how they did this.

1. turn the old one into a metapackage

• Create a new gem (named smart-cropper)
• Add smart-cropper as a dependency to croptoelie (old gem)
• Remove all lib, bins and other code from croptoelie

A problem I see with this, is that it is too transparent, people might not be aware that the gem they use is no longer maintained.

Another problem is that versioning becomes harder: I would have to bump the version of the old "metapackage" each time I released a new version of the renamed (smart-cropper) gem, or people would never get a new version.

2. throw deprecation warnings

I could send out a release of the old gem that simply throws deprecation warnings with a message that people should install that new gem.

The problem I see with this is that it can be quite intrusive and might turn people[1] away from the gem altogether.

Are there other options? Is there something built into "RubyGems" to cater for the changing of the name?

[1] not that too many people are using it; because of the name it is hard to find. :)

Answer 1

You simply push the new gem with the new name and tell your users about the new name. There is no mechanism for renaming gems. -- RubyGems support staff, February 20, 2012

To that end, the following are some tips (some of which I see you have already done).

in the old gem, throw deprecation warnings

Example:

warn "[DEPRECATION] This gem has been renamed to _____ and will no longer be supported. Please switch to _____ as soon as possible." 

in old gem's .gemspec file

Display a message after the old gem is installed, using the post_install_message attribute. The following example is based on the Heroku gem.

gem.post_install_message = <<-MESSAGE !    The '_____' gem has been deprecated and has been replaced by '_____'. !    See: https://rubygems.org/gems/_____ !    And: https://github.com/_____/_____ MESSAGE 

on the old GitHub repo's page

-1- At the top of the page: Add a description to this repository: (provide the new name)

Moved to ---> "_____". 

-2- At the top of the page: Add a website to this repository: (make this the URL of the new repo)

https://github.com/_____/_____ 

-3- Upload a new README.markdown:

# OLD NAME  Moved to [new name](https://github.com/_____/_____). 

-4- Consider removing all non-essential files.

in the new gem's .gemspec file

Include the following notice at the end of the summary or description attribute:

Formerly known as '_____'. 

yank the old gem

At some distant point, you may want to remove the old gem from RubyGems. As of RubyGems 1.3.6 and gemcutter 0.5.0 (circa February 2010), you can use gem yank to remove your gem from being available with gem install and the other gem commands. However, the gem will still be available for download for two main reasons:

1. Other gems may have been pushed that depend on your gem.
2. A mass deletion of important community based gems can be easily prevented.

Go here for more info about yank.