Skip to content

How to do Deprecations (When removing database columns)

BertoCQ edited this page Jan 31, 2018 · 2 revisions

Whenever we're going to remove columns from the database, we need to be aware that consul is being used on many forks that may loose data on those columns "by surprise". If we're not using anymore those columns the correct procedure is to:

  1. Totally avoid using them anymore on this PR (I suppose that's the case so 👍 )

  2. Add in the "Warning" section of this PR that the Changelog for next release (v0.13) should include a Deprecation warning about the usage of those two columns. (Best would be to directly include yourself that reference but the designated manager will do it if you just add the notice)

  3. This first PR should include a rake task to migrate (if needed) the values, and state that on the Changelog at the deprecation section as well.

  4. Create a separate PR, and clearly state that it should not be merged until 2 releases in the future (that's relesae v0.14) and on it we'll just include that migration that removes the columns. At the changelog it will be included as a simple change with a reference the first PR for extra contents and "reminder" that if the rake task hasn't been ran yet, before updating up to v0.14 its a good idea to do it

Why all this procedures

Think that few forks update their codebase with consul#master (and in fact NONE should do it as master is often broken and we can guarantee otherwise). So forks that update release by release... get a "big chunk" of changes at once. Many will not read release notes (that's their problem) but for sure almost none will read the code diff :) and then won't notice the migration that removes columns (along with data).

So for those great maintainers that both read changelog and code diff... they'll face a hard situation as deploying that "chunk" of changes will run the migration and destroy the data before they're even able to access the rails console to run the rake task 🤔 .

Yes... some people fix this by "integrating" the rake task code inside the migration but in my experience that's not something nice as those migrations are often hard to revert and you're mixing to intentions (database changes and data changes).... but I've done it in the past in different projects (this is the most special one we'll ever work on because of the forks)

The point is ... will it hurt anyone if those no-longer-used columns live along with the data inside for the time that will take those maintainers to upgrade to the next version release? Answer is no in almost all cases, so the really easy and safe path is to do things in two steps, with a deprecation warning, and giving enough time to run (or even modify if there are customizations in the fork's side) the rake task.

Clone this wiki locally