Specify version number each class was introduced

[ricardograca]

I see a lot of issues where users clearly read the online Readme and tried to use a Faker class only to receive a NameError: uninitialized constant Faker::Whatever.

Currently there's no indication whatsoever when each class was introduced. It would be very useful if this information was present in both the Readme.md file and each class' individual readme file.

Example README.md (completely random versions since I don't actually know the correct ones yet):

Contents
--------

- [Installing](#installing)
- [Usage](#usage)
  - [Faker::Address](doc/address.md) (since 1.5.3)
  - [Faker::Ancient](doc/ancient.md) (since 1.6.0)
  - ...

Example class readme file:

Faker::App

Available since version 1.3.6.

Faker::App.name #=> "Treeflex"

Faker::App.version #=> "0.7.9"

Faker::App.author #=> "Daphne Swift"

Related issues:

#620, #688, #812, #851, #856, #917, #935, (hypothetical issue that I almost created)

There are probably more, but I didn't look in all the closed ones, so this seems like a recurrent issue.

[darylf]

I attempted to solve this with Pull Request #974

[stympy]

That's an interesting idea, but what would one do when merging a newly-created class? What version would you enter, since there isn't a released version yet? If instead of a number you put "pending", "master", or something like that, then you'd need to go back to all of those new classes when making a release and update them with the new version number. Also, how would you handle new methods on old classes?

Here's an alternative idea: How about I just batch up the addition of new classes and the addition of new methods, and then always do a gem release after doing a batch? That would prevent the README from being behind the most recent release.

[ricardograca]

... what would one do when merging a newly-created class? (...) If instead of a number you put "pending", "master", or something like that, then you'd need to go back to all of those new classes when making a release and update them with the new version number.

I see your point. That's an extra development burden for sure, but good documentation doesn't create itself, so not sure if there's an easy way around that.

Also, how would you handle new methods on old classes?

Probably in a similar way. Something like:

# Faker::App
Available since version 1.3.6.

Faker::App.name #=> "Treeflex"
Faker::App.version #=> "0.7.9"
Faker::App.author #=> "Daphne Swift" (available since 1.4.0)

I just batch up the addition of new classes and the addition of new methods, and then always do a gem release after doing a batch?

@stympy That could work, but still leaves the problem of identifying methods that were added after the initial class release.

[b264]

updating to the latest version is a normal first step when a library is not performing correctly

[stefannibrasil]

Hey, folks. In an effort to lighten our load as maintainers and be able to serve you better in the future, the faker-ruby team is working on cleaning out the cobwebs in this repo by pruning the backlog. As there are few of us, there are a lot of items that will simply never earn our attention in a reasonable time frame, and rather than giving you an empty promise, we think it makes more sense to focus on more recent issues. That means, unfortunately, that we must close this issue.

Don't take this the wrong way: our aim is not to diminish the effort people have made or dismiss problems that have been raised. If you feel that we should reopen this issue, then please let us know so that we can reprioritize it. Thanks!