Reorganize README.md and divide the content in "unreleased" and "latest version"

[jcohenho]

No description provided.

[vbrazo]

This namespace wasn't released yet. Which Faker::Games module are you interested in using?

[vbrazo]

If you wanna use them, you need to point your gem path to the master branch @jcohenho

[jcohenho]

Ah I just realized that. Wow you're quick! Was trying to use the Faker::Games::HalfLife one. I'd like to stick to the versioned release so I'll find something else, thanks!

[vbrazo]

Try Faker::HalfLife

[vbrazo]

We added this namespace in this PR #1412. Unfortunately our README.md has changes that aren't released yet. I'll try to find a way to reorganize the README.md. Maybe we could have two different contents:

• unreleased content:
• latest version content

[vbrazo]

I tried to think a bit but I couldn't come with a good suggestion. We're going to release a new version soon, so this issue will disappear. I'll keep this problem in mind.

[vbrazo]

Let's keep this issue open. Maybe someone can suggest a better README.md.

[Michael-Overall]

Would a possible improvement be as simple as adding a tag like [UNRELEASED] in the link text for each of you links in in README.md?

If you tell me what to look for in determining what is/isn't implemented, I can try to add these labels.

[vbrazo]

If you tell me what to look for in determining what is/isn't implemented

@Michael-Overall Here is the list of all the versions. You should pull/copy the latest version and compare this version with the master branch to propose the suggested changes. When copying 1.9.1, you should have access to the old README.md and the doc files.

A couple of things before you start:

• Besides adding new Faker objects, we've been introducing namespaces recently. The problem reported in this issue was related to a new namespace. E.g. Faker::HalfLife became Faker::Games::HalfLife.
• When wrapping an existing object to a namespace, we were just editing the docs file. Just updating doc/half_life.md. I think we need to have the old documentation files and the newest ones inside the master branch, so I'd recommend creating a new folder inside the doc folder. It could be 1.9.1. We should have all the old documentation files inside this folder.
• I'd also create another folder inside the doc folder and its name should be unreleased. Then I'd add all the documentation files that are currently in our master branch.

I think these 2 folders would help people a lot. The next step would be updating the README.md and come up with a good idea to separate these 2 versions that have been confusing users for a while.

What do you guys think about my suggestions?

[jcohenho]

@vbrazo I think the docs versioning is a good idea. As far as the README, why not just keep only released documentation there? Anyone is always welcome to look at the source code and prod for unreleased functionality. Also just want to let you know that Faker::HalfLife doesn't work either.

[vbrazo]

@jcohenho you're right. I got confused with the Games namespace and its recent deprecations.

Faker::Games::HalfLife was introduced in this PR #1381 and it hasn't been released yet. If you go there, you'll see that the contributor initially introduced Faker::HalfLife and I asked him to add the namespace because we were migrating and deprecating all the Games objects.

We don't have this object in Faker 1.9.1. If you wanna use this object, you need to point your gem to the master branch directly.

[vbrazo]

I agree that the latest version - 1.9.1 content should be in our README.md.

Unreleased could be in a separate file and we could advice contributors to update this unreleased content when adding/removing Faker objects. Otherwise when we release a new version of the gem, the owner will need to go there and update the README.md.

[vbrazo]

@Michael-Overall @jcohenho I just fixed the issue. Now the README.md has the v1.9.1 objects. No more confusion 🤣 🤣

We have a separate file for the unreleased objects. I'll let the contributors know that this file exists.

[Michael-Overall]

Noted. I was just about to write a lengthy comment trying to confirm where the most recent, the old, and the current documentation was supposed to come from, so @vbrazo saved us all from that 😆