Consider documenting Elasticsearch migrations

Problem to solve

Follow-up issue to this comment

When Elasticsearch migrations are skipped during the upgrade process, it can cause issues down the line with indexing. This leads to time consuming troubleshooting where it can be a challenge to identify if migrations have been obsoleted or if there are other issues at hand. Re-indexing from scratch can also be time consuming for customers with large instances. It can also be difficult to know what migrations were pending or present prior to each upgrade.

Proposal

I'm proposing that we document all Elasticsearch migrations in a chart or similar, where we can provide more guidance such as:

• Name of migration
• When it was introduced
• It's purpose
• When it was obsoleted and in what version

It would also be good to have guidance surrounding removal process for migrations. This will allow customers and support engineers to more easily identify obsolete migrations.

Add a rake task and spec to make sure that all migrations are included in the dictionary, otherwise we might forget to add it.

Other details

• We have some good information on our development page, but the proposal is primarily aimed at troubleshooting from a customer and SE perspective.