Add docs for SO migrations

[joshdover]

Summary

This adds docs for:

• Saved Object migrations in general
• A pattern for nested saved object migrations, with a complete example

[stacey-gammon]

I don't think the types in this example will work:

https://www.typescriptlang.org/play?#code/LAKALgngDgpgBAYQBYEMBOYCyBLA5mlMbAewDsAxUgHmXTAGUxD4YAPMGUgEwGc5iARgCsYAYzBwAvP2FiwAPilwAFKNQYAIsVEAuGSPEBKKYtoZGzANyhQ2UhzQAzFKPhmwNdQyYc4bDtx8ggYS0sFyigDeoHBwkLB6PGBodrjWILFonFwwaKpeeu4WHAA0fgA2MAC2nGB6ABIAKpgAMgCilTX2hnoAbsTYXOmxolnMyj2IXsUww3C4MFh4BERkPBN6AEpixGhcVEkppLhl7jj4hCQU1EU+MPLy6QC+NiCiaxJqdHzSpDAA7nBMCgoAdkqlTl55BN0qBHABXUjiK5wLK4bBJXKeOgzPzsbJBWTiaFfDCFLzY8x3eTGaIZOCksA8AB0PEW+TozPiMDKjMMz1edgczlccAAQuhbswAIwABllcDpsVYAEFWBjEuDjnMIGqNXBDqk5nYcqwAAqEBykTVHNKgF4gIW5EXwCVoKUcaVyxUxOCq9U8G1G326gNB7W+riEFD0YjwtCuPRK2JwE1sC1gK3hu30h0O0BojEOKhuj0wOWy6HJ7l6ADkAnQAFpGbWSr6stxchNFXAnm36aMYONaajFvHSD3-fra45iMRW3BQ9OG2gF1GmLH44me2nzZbcta4PWUAAvWu93t930LJYXVakda032ZMdoCfJlNH6XM7+y2t6ZRiHKLgyz0UtpjuCtJnAnFIO9SRFGUD9Pz9PVA34YCy2ZKceH7FCUyXdCgJAiDmGZQi8PwuB1xjOMExgJNU07PdMwPPRiKwmjN3o3tnxTJ5DD4h1YjzflfVeIA

[stacey-gammon]

Is there a way we can automate this so the ChartList plugin author doesn't have to manually add a new migration in here every single minor? It'd be super easy to forget.

something like

 const migrationMap = {
    '1.1.0': my1_0_migration(),
     '2.5.0': my_2_5_migration()
  }

 // For versions that the Chart List plugin doesn't have any specific migrations for, they still want to
 // let each chart have an opportunity to add migrations.   Rather than require this to be manually added
 // every time, automatically fill in any versions that don't have manual migrations. 
  KIBANA_VERSION_LIST.foreach(version => {
    if (migrationMap[version] === undefined) {
      migrationMap[version] = {
              ...chartList,
              // For each chart, apply the chart migration for this version if it exists
              charts: chartList.map(
                chart => chartMigrations[version] ? chartMigrations[version](chart) : chart
             )
      }
    }
  );

  return migrationMap;

You would still need to remember to migrate the nested state inside each my_x_migration fn. Couple perhaps be remedied by some more refactoring.

[mshustov]

Or even make it a part of registry API:

charts: chartList.map(state => plugins.charts.migrateTo(version, state))

[mshustov]

should be BarChartState110 ?

[mshustov]

that's basically the same as type ChartMigrationFn = (input: Record<string, any>) => Record<string, any>, we cannot guarantee the output type for every migration

[mshustov]

Or even make it a part of registry API:

charts: chartList.map(state => plugins.charts.migrateTo(version, state))

[rudolf]

As per elastic#71430 (comment) I'm merging this into that pull request and will remove the nested migrations documentation.