README in master branch doesn't correspond to the currently released gem.

[GBH]

Pretty confusing when include Virtus.model crashes even though documentation claims it should work. If you're working on changing api for 1.0.0 keep it in a non-master branch until gem is released that reflects proper docs.

Really like this gem though :thumbsup:

[greyblake]

+1

[mbj]

I dont like this strategy: If you wanna have docs that correspond to release, use the README.md from release. Or use a YARD-doc renderer on the web. Master branch reflects current development. And current development might not be released.

[solnic]

Sorry but as @mbj pointed out - README is part of the source code which reflects whatever is currently happening in development. I will make sure to add info about version number to README though. I'll keep this open until it's done.

1.0.0 will be released tomorrow btw.

[solnic]

ping @elskwid - wdyt about adding version number to readme?

[GBH]

@mbj @solnic Very much disagree. When I need to figure out how a gem works I go to github and scroll through the readme. I'm sure I'm not the only one. Also master branch doesn't need to mean current development. For example, if you use gitflow you have 'develop' branch for that. http://nvie.com/posts/a-successful-git-branching-model/

[elskwid]

@solnic - If you mean just a reference to the version in the README, I'm all for it. For example, Intridea does this for Grape and I love it.

@GBH - While it's true that master is arbitrary in its name and function, the entire rom-rb team (and many others) use master for ongoing development. Adding a prominent version number to the README will help to signal that you are reading versioned content.

[solnic]

@elskwid yeah I saw that in grape too and liked the idea

[GBH]

@elskwid makes sense. As long as it easy enough to understand what you're looking at. For example current readme has this displayed: So you can't blame me for assuming that examples in readme correspond to that gem's version number.

[elskwid]

@GBH - good call! As we work through the docs we'll make sure that this is as clear as it can be. Thank you for the feedback. I'll ping this issue when I have some docs added on my fork so you can take a look.

[elskwid]

By the way, docs are being worked on in #205.

[solnic]

@GBH sorry about that, I was aware of this actually and didn't manage to address this problem until now, we (@elskwid and me) are working on new docs so this will be fixed :)

[dkubb]

@elskwid fwiw, In my gems I consider the master branch to be a "releasable state". I try to work as if everytime I push to master it also pushes a gem up to rubygems that I would use in production. I tend to keep feature branches open a bit longer and test things against those, but once I merge into master it's usually because I think it's good enough to use.

It doesn't mean I don't sometimes make mistakes, or have the docs drift out a bit but I try to keep master basically on par with the quality I'd push a gem out with.

I don't know if others work like this. I think it's a useful model to try out if anyone is interested.

[solnic]

@dkubb but this doesn't change the fact examples in readme must always reflect released version, right? I may want to add a new feature to master, update readme but hold off with the release for whatever reason.

[elskwid]

@dkubb, Thanks for the clarification. Even in your workflow it means master is not in lock-step with a released gem which is what @GBH is referring to (I think). I like the idea of referencing the gem version in the docs even if I also worry they'll get out of sync - which is more a matter of discipline and memory.

Do you have any tips, tricks, or strategies that you use that may help?

[mbj]

TBH I think a:

This Readme belongs to the code that is being distributed next to it.

Should be enough ;)

[solnic]

It does now.