Reference: rubygems/guides#370

Problem

When adding a non-development dependency to a gemspec, it can be unclear what to use between add_dependency and add_runtime_dependency.

Let me elaborate by doing a comparison across different places.

In the docs and generators

• add_dependency is more prominent in the Bundler guide on how to create a Ruby gem, and it is mentioned in the gemspec generated by bundle gem:

    ...
  
    # Uncomment to register a new dependency of your gem
    # spec.add_dependency "example-gem", "~> 1.0"
  
    # For more information and examples about making a new gem, check out our
    # guide at: https://bundler.io/guides/creating_gem.html
  end
  

  In both cases add_runtime_dependency is not mentioned.

• add_runtime_dependency is more prominent in rubydoc and in the specification reference. add_dependency is mentioned as an alias, feeling more like an aside.

In the wild

• A sourcegraph search shows 92.3k results for add_dependency, and 33.6k results for add_runtime_dependency, so add_dependency is used 73% of the time.
• A github search shows 202k files using add_dependency, and 87k files using add_runtime_dependency, so add_dependency is used 70% of the time.
• In my collection of manually curated real world Ruby apps, with a small sample size of 63 repos, add_dependency is used in 35 gemspecs, and add_runtime_dependency is used in 19 gemspecs, so when there is a gemspec add_dependency is used 65% of the time.

In the code

• In Gem::Specification, add_dependency is currently an alias for add_runtime_dependency:

  alias_method :add_dependency, :add_runtime_dependency

• After doing a bit of Git history archeology 🕵️ , it turns out that add_dependency was the original method for adding a dependency, going all the way back to 2003 and maybe more. The notion of development dependencies was introduced in 2008 when add_development_dependency and add_runtime_dependency were created, and add_dependency got relegated to an alias. I don't know if this relegation or downgrade in status was conscious or just happened by chance and one had to be picked as the alias.

Interpretation

I don't know if there was a conscious push for either add_dependency or add_runtime_dependency, or if both just happened organically. It seems to me that the latter case is what happened, but maybe someone who is more well versed into rubygems can shed more light on the matter.

The current state of affairs seems to be that add_dependency is the more popular way in terms of usage, and the Bundler guide and bundler gem code generation suggestion only mention this way.

Possible solutions

@deivid-rodriguez mentioned some possible solutions here. Here is is a non-exhaustive list with my suggestions as well:

1. Edit the specification reference to show separate entries for aliases. Maybe by making them look as important as non-aliased methods like this:

   

   This is similar to what the Rails API does for example here.

2. Or invert so that add_dependency becomes the main method, and add_runtime_dependency the alias, which would look like this:

   

3. Or use add_runtime_dependency in the bundle gem generated gemspec and maybe use add_runtime_dependency in the Bundler guide

4. Maybe this is a non-issue and there is no main way to go, and it all depends on what context you're in. add_development_dependency could be considered a nice symmetrical counterpoint to add_runtime_dependency when using both in the same gemspec.

   If using the Gemfile for development dependencies and gemspec for non-development dependencies, which is what currently happens when doing bundle gem, then the way it is currently done (i.e. suggesting add_dependency in the generated gemspec) can make more sense, as in the gemspec there wouldn't be any development dependency to be a counterpoint to.

   If no way is more preferable than the other, then we can just close this issue. One would just use what feels right depending on the context or their personal preferences. Although I would argue that doing something like solution 1 could still be useful to feature add_dependency on a more equal footing as add_runtime_dependency.