Suggestion for releasing as a gem

[pbrisbin]

I think we should stop using this as a git source everywhere and start pushing to ruby-gems and respecting SemVer for ourselves. We've already got a situation where some applications rely on the now-removed Indexes module, so we'll want to stay pinned until we can address that, but other applications are following master.

Suggestion:

• Release d7684b7 as 1.0.0

  This is the latest point on master before the most recent breaking change. This is what applications that currently rely on the Indexes module will depend on. If they rely on #rescue_duplicate_key_error, the upgrade path is clear, but if they rely on .ensure_index they'll need to not do that (it's considered dangerous) before upgrading.

• Remove #save

  This method is dangerous for reasons which I'll outline when removing it (and probably document in the README, because its absence will be surprising). But it's the only breaking change I know of on the roadmap, so might as well do it before releasing again.

  I think we can just make #save safe by implementing it with $set instead.

• Release master as 2.0.0 and update current application Gemfiles

• Proceed with development, follow SemVer

WDYT @codeclimate/review ?

[wfleming]

Release d7684b7 as 1.0.0

What's the thinking behind backdating instead of just cutting a 1.0.0 with a current version of master we're happy with? Seems simpler. And if we should be getting clients off of sha-locked-versions, I think it's actually kind of nice if client's can't switch while still relying on bad behavior.

[pbrisbin]

I considered removing git references from Gemfiles to be a motivation/benefit. So allowing clients that are intentionally staying back to also remove the git reference was valuable. Assuming that we won't address those clients for some time, an opaque git reference seems more dangerous than a specific <= 2.0.0 in those Gemfiles.

[wfleming]

That makes sense. I didn't realize we had that many old clients still using bad behavior.

[maxjacobson]

Great plan!

There are a few organizational things I think we'll need to (or should) do before releasing (I'm sure you've thought of some of this already, just kind of brain dumping 😄):

• manage the version in a version.rb file which is referenced from the gemspec (this is the convention when you run bundle gem minidoc to scaffold a new gem)
• add a code of conduct
• use the rake task to release the gem, which will automatically create and push a git tag, and then push to rubygems
• figure out who is going to have permission to push releases to rubygems and how we'll manage that
• update the gemspec to reference the new homepage post-move
• start keeping a changelog.md or history.md to document the changes in each released version

[pbrisbin]

@maxjacobson that all sounds great. Any interesting in being kind of a gem-czar for us? Document how we manage OSS gems like this, handle taking this one through that process, getting our other gems in-line, etc?

[maxjacobson]

Sure, I'd be happy to do that. It might be a bit tricky to add the organizational stuff to what you're calling 1.0.0. I'm tempted to suggest branching off from that commit onto a 1.0.0 release branch and backporting any organizational changes to that branch ahead of releasing it

[pbrisbin]

What's the downside to pushing the commit I linked as-is as 1.0.0, then including the organization fixes you've mentioned in 2.0.0 when we release master next?

[maxjacobson]

Hmmm, I suppose they're really minor. For example, if we expose a Minidoc::VERSION constant, but it doesn't start existing until 2.0.0, future hypothetical minidoc extensions can't check that constant's value to make decisions about behavior (which is a thing the Mongoid community has to deal with). I think the idea is just that if you're going to establish conventions, it's good to establish them from the beginning. But I think it's not a huge deal 😄

[pbrisbin]

Another option is to release the linked commit as 0.0.1 to indicate that we really didn't get our act together until the 1.0.0 that'll come later, after addressing all that.

[pbrisbin]

By the way, Minidoc::VERSION does exist.

[maxjacobson]

oh! OK. We should probably release as 0.0.1 then, to match that. If we want to release as 0.1.0, maybe we branch off and change that value and then release that.

[pbrisbin]

Good point. I forgot we'd have to change that to back-date. My vote is to release that commit as what VERSION is in that commit (0.1.0 was a typo I quickly corrected). I'd really like to avoid maintenance branches.

[maxjacobson]

👍 I can start work on releasing 0.0.1 soon, then. Will wait a bit to give others a chance to give input