7-to-8 migration guide

[hjoliver]

Check list of items that will need to be noted (ADD TO THIS LIST AS NEEDED)

• suite.rc -> flow.cylc
• restart from Cylc 7 DB not supported
• new run semantics (cylc play etc.; and the run1, run2, ... sub-dirs
• new scheduling section syntax
• deprecated config items: recommend upgrading them
• task state name translation (was 13 states, now 8)
• named state checkpoints gone
  • Remove named checkpointing cylc-flow#3891
  • recommend use of reflow-based warm start: checkpoint: re-evaluate purpose of checkpointing cylc-flow#3864 (comment)
• platforms concept explainer

Transferred from @oliver-sanders comment below:

Suggested topics:

• cylc install (w/ note on [install]source dirs & run numbs/names "safe run semantics")
• platforms
• play / pause / stop (w/ note about hold/release)
• reflow
• remote installation (w/ note on [scheduler]install for people who used to use rose suite-run)
• runahead limit changes (w/ recommendation to use queues where possible)
• symlink dirs (for people who used the Rose root dir config to do this, note per-workflow conf is no longer possible) Improve symlink dirs documentation #369
• suicide triggers migration guide: add section for documenting cylc8 changes #241
• suicide triggers update post possible SoD changes.
• rose suite-run to cylc install migration (now remembers options)
• rose stem (now provided by cylc install)
• allow implicit tasks (note: doesn't affect Rose2019 users) (note: add link to migration page in warning message). Cylc 7 back compat & remove outdated caveat #304 Add link to migration guide in implicit tasks warning cylc-flow#4572

[oliver-sanders]

Added a section for documenting Cylc 8 changes in #241, just need to populate it!

Suggest the following format:

1. An admonition at the top of the page quickly conveying whether this is something the reader should delve into.
2. 1-2 line description of functionality if necessary.
3. Quick description of the change.
4. Example diff if required.

Example - https://github.com/cylc/cylc-doc/pull/241/files#diff-705a4752ecedd74e974b38897f45a8313a1042872eb7ead9056dd54080a37b61

These sections should be short, avoid documenting the actual feature here, just convey the change and link through to the main documentation.

[oliver-sanders]

Suggested topics:

[checkpoint list moved to the main Issue description]

[wxtim]

I'm going to have a go at writing sections on Cylc install / reinstall, and subsequently stem.

[MetRonnie]

suite.rc -> flow.cylc

I would say this is covered by https://cylc.github.io/cylc-doc/nightly/html/7-to-8/summary.html#admonition-0

restart from Cylc 7 DB not supported

I think that could go in https://cylc.github.io/cylc-doc/nightly/html/7-to-8/summary.html#backward-compatibility

deprecated config items: recommend upgrading them

Covered by https://cylc.github.io/cylc-doc/nightly/html/7-to-8/summary.html#admonition-1

[hjoliver]

Oops, I had forgotten about this issue. Some of the items done already, will review... [Most main description checkpoints checked off]

[hjoliver]

restart from Cylc 7 DB not supported

I think that could go in https://cylc.github.io/cylc-doc/nightly/html/7-to-8/summary.html#backward-compatibility

Done - added to #310

[hjoliver]

Checked off named checkpoints are gone - noted in the 7-8 Major Changes section.

[hjoliver]

Checked off remote installation. Covered in 7-8 Major Changes, with links that follow through to the relevant config.

[hjoliver]

All done. 🎉