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…

Accepted Answer

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:

- Other gems may have been pushed that depend on your gem.

- A mass deletion of important community based gems can be easily prevented.

Go here for more info about yank.

How to rename a gem?

Solution

Problem