Add migration section to the pipeline documentation topic

[ptitzler]

Add a new migration section to the pipeline topic in the user guide. The section outlines the actions that a user must take if an attempt is made to open a pipeline file what was created using an older or newer Elyra version that is incompatible.

Future release notes will link to this section, whenever a release introduces breaking changes that require pipeline migration.

Migration is currently only supported through the Visual Pipeline Editor until #2647 is delivered.

What changes were proposed in this pull request?

See above

How was this pull request tested?

Reviewed the output of make docs.

Developer's Certificate of Origin 1.1

   By making a contribution to this project, I certify that:

   (a) The contribution was created in whole or in part by me and I
       have the right to submit it under the Apache License 2.0; or

   (b) The contribution is based upon previous work that, to the best
       of my knowledge, is covered under an appropriate open source
       license and I have the right under that license to submit that
       work with modifications, whether created in whole or in part
       by me, under the same open source license (unless I am
       permitted to submit under a different license), as indicated
       in the file; or

   (c) The contribution was provided directly to me by some other
       person who certified (a), (b) or (c) and I have not modified
       it.

   (d) I understand and agree that this project and the contribution
       are public and that a record of the contribution (including all
       personal information I submit with it, including my sign-off) is
       maintained indefinitely and may be redistributed consistent with
       this project or the open source license(s) involved.

[elyra-bot]

Thanks for making a pull request to Elyra!

To try out this branch on binder, follow this link:

[kevin-bates]

This looks good to me and I'm approving but do have some minor questions.

• Should we make mention of when the pipeline version can change? I.e., let users know that pipeline versions can change on major or minor releases, but never in a patch release?

• Is the pipeline version displayed anywhere (preferably in the CLI) so users could determine their pipelines will require a migration? Do we publish the expected pipeline version anywhere? If a site has dozens/hundreds of pipelines, the operator may want to drive this process via the CLI before exposing users to the extra step.

Adding @ajbozarth as a reviewer as well.

[ptitzler]

• Should we make mention of when the pipeline version can change? I.e., let users know that pipeline versions can change on major or minor releases, but never in a patch release?

done

• Is the pipeline version displayed anywhere (preferably in the CLI) so users could determine their pipelines will require a migration? Do we publish the expected pipeline version anywhere? If a site has dozens/hundreds of pipelines, the operator may want to drive this process via the CLI before exposing users to the extra step.

The elyra-pipeline describe does. If JSON output is produced i should be easy to identify those pipelines that do require migration.

{
    "name": "my",
    "description": null,
    "pipeline_type": "APACHE_AIRFLOW",
    "pipeline_format_version": 7,
    ...

The caveat is that we don't (in for some scenarios cannot) provide a hint how pipeline versions map to Elyra versions.