Expand Gemfile.lock management recommendations

[srizzo]

What was the end-user problem that led to this PR?

The problem was that the current Gemfile.lock recommendations for gem development were incomplete and could lead to situations where gems are published with outdated or incompatible dependencies. Users were experiencing confusion about best practices, particularly around CI processes and dependency management across different Ruby versions.

What was your diagnosis of the problem?

My diagnosis was that the documentation needed to address three key gaps:

1. The limitation of using a single Gemfile.lock with multiple Ruby versions
2. The timing issues with scheduled dependency checks (both Dependabot and daily CI builds)
3. The importance of dependency verification during the gem publishing process

What is your fix for the problem, implemented in this PR?

My fix adds three important clarifications to the documentation:

1. A note about maintaining separate Gemfiles for different Ruby versions when using Dependabot
2. A recommendation to regenerate Gemfile.lock before publishing
3. More context around when and why to verify dependencies

Why did you choose this fix out of the possible options?

I chose this fix because:

1. It maintains the existing recommendations while adding crucial missing context
2. It addresses real-world scenarios that developers encounter when managing gems
3. It provides actionable guidance for the gem publishing process
4. It helps prevent the release of gems with outdated or incompatible dependencies
5. The changes are concise yet comprehensive enough to guide developers toward better practices

[deivid-rodriguez]

Hi, thank you for trying to improve documentation.

Let's start with the first bullet point: "The limitation of using a single Gemfile.lock with multiple Ruby versions". Do you have a more elaborate explanation of this limitation? Maybe this is no longer an issue in your case with rubygems/rubygems#8251? Before documenting workarounds, I'd like to make sure we can't provide better solutions.

[srizzo]

Hi, thank you for trying to improve documentation.

Let's start with the first bullet point: "The limitation of using a single Gemfile.lock with multiple Ruby versions". Do you have a more elaborate explanation of this limitation? Maybe this is no longer an issue in your case with rubygems/rubygems#8251? Before documenting workarounds, I'd like to make sure we can't provide better solutions.

Thank you for your quick reply. As of now, as far as I understand, different ruby versions can yield different Gemfile.lock. This might change with the PR you mentioned, but this is currently not the case.

As far as I understand, from dependabot/dependabot-core#4987, at the moment dependabot will simply use the lower bound ruby version.

Is that right?

[srizzo]

If you can have a single Gemfile.lock for all ruby versions and Dependabot play well with that, that will be amazing, thanks for the PR.

However, at the moment, it might lead to issues with ruby versions if I understand it correctly.

I'm also happy to rephrase the PR in a way that better fits your plans, or create another one to update it once your PR is merged

[srizzo]

Not sure how it would work with respect to gems, though. Let's say you have a Gemfile with gemspec and a gemspec with s.required_ruby_version = '>= 2.7'.

Would it get all variants of dependencies for all ruby versions, including 3.x?

[deivid-rodriguez]

Thank you for your quick reply. As of now, as far as I understand, different ruby versions can yield different Gemfile.lock. This might change with the PR you mentioned, but this is currently not the case.

Yes, that's the idea. Would you be willing to try out the PR and see if it works for your case? Also, it'd be nice to see how it works with Dependabot too.

As far as I understand, from dependabot/dependabot-core#4987, at the moment dependabot will simply use the lower bound ruby version.

My recollection is that Dependabots tries to auto-detect the lowest Ruby version that you want to support, and then indeed sets up an extra lower bound constraint on the Ruby version, so that you don't get accidental updates to the lockfile that break support for the Ruby. But that behavior seems like it would make it even easier to maintain a single Gemfile.lock file.

[deivid-rodriguez]

I'm also happy to rephrase the PR in a way that better fits your plans, or create another one to update it once your PR is merged

I'd say let's wait for next version to be released with those improvements, then you try it and we reevaluate the situation and discuss whether anything (either docs or functionality) needs improving.

[srizzo]

I'd say let's wait for next version to be released with those improvements, then you try it and we reevaluate the situation and discuss whether anything (either docs or functionality) needs improving.

Sure, but please consider the other point of my PR.

Even if Dependabot can reliably generate a PR with a Gemfile.lock that cover the range of ruby versions in the gemspec, there's still the timing issue. It takes time for Dependabot run (and its PR to be merged), and until then the tests might be producing false positives, right?

Why not recreate the Gemfile.lock in the CI before running the tests and publishing the gem? Or alternatively, fail the build if the Gemfile.lock is know not to be up-to-date?

IMHO Dependabot and or a scheduled daily build are good to proactively get notified with breaking changes in dependencies, but the job that actually tests and publishes the gem is the last line of defense against incompatibilities and the most accurate place to update dependencies and run the tests.

What are your thoughts on this?

[srizzo]

Yes, that's the idea. Would you be willing to try out the PR and see if it works for your case? Also, it'd be nice to see how it works with Dependabot too.

I don't have a specific case other than a large client with dozens of (private) gems to maintain and CIs that IMHO are not optimal for the reasons I'm trying to clarify in this PR.

We did have a recent case were a Gemfile.lock had different results across ruby versions (as expected, before the PR). I can try and get more details, but I can't promise to do so in a timely manner, unfortunately.

[deivid-rodriguez]

I'm not opposed to adding a note like the one you are suggesting. It's indeed good to get information about any new dependency releases that may not work with your gem 👍. Some people may not want to bother, I think it depends on the situation, so "consider" seems like a good wording to me.

The issue is of course always going to be there, even if you run your tests with up to date dependencies, there can always be a new release right after you push your gem that breaks something. But I guess it's something easy you can do to try provide a smoother experience.

Let's see if other maintainers chime in, but I'm personally good with such note.

[indirect]

This note seems like a pure improvement to the docs, to me. Thanks for taking the time to write it and explain your reasoning!

[deivid-rodriguez]

Cool, can you update the PR to only mention the point about testing without a lockfile before pushing a release, @srizzo?

[srizzo]

Cool, can you update the PR to only mention the point about testing without a lockfile before pushing a release, @srizzo?

Thank you. I've updated it.

[olleolleolle]

@srizzo Fantastic, thanks for staying with it, now merged!