[Rose/cylc]: advice on best way to record purpose of a rose app?

Rose Rose Support
1

Hoping to sense-check on the best way to record the purpose of an app (task) in a suite - I think I can see how to do this with cylc, but wanting to check if there’s a rose way of doing this.

Longer context for this below - TLDR: I want to a mechanism to give a ~explicit, ~easily-discoverable description of a ~complex app’s purpose, so I don’t have to:

  • dig deep-down in (say) the app’s scripts, and any documentation I’ve hopefully put there
  • rely on encoding this within the app name, already ~long as am trying to stick to the (sensible!) naming convention guidelines, a la model_purpose-of-app_<optional-suffix-eg-"cold">.

I’ve not yet used it / encountered it much in others’ suites, but hunting for options here, I’ve found cylc’s runtime task metadata items, which look like they might meet my aims - and indeed seem to be recommended by the style guide.

And if documenting apps like this makes the suite.rc too long, I guess I could hive such [runtime] ->[[my_app]]->[[[meta]]]-> title / description entries off into separate files (e.g. in ./app/my_app/title-description.rc, and use the include file mechanism in the suite.rc in order to:

  • actually include this, so this info is made available in the GUI
  • expose existence of this file within suite.rc, so those reading suite.rc can discover that title/description info for app exists, and where to look for it

However, before I charge off and do this, wanting to check whether the above approach is sensible? Or whether there’s a way to provide such information via rose instead? Say something similar to the help metadata for a setting, but as metadata recording the purpose of the app?

Asking this as I guess this could be considered part of rose’s “[create] metadata to facilitate ease of use by others” function. And might be especially helpful if (say) you wanted to provide guidance which differentiated between the behaviours of the main rose config and optional configuration(s).

I guess this differentiation could still live in cylc’s [[[meta]]] entries for the app in suite.rc - e.g.:

[[my-app]]
[[[meta]]]
title = Install code
description = """
Installs code from /foo
If optional rose config bar is used, https://baz is used as installation source
"""

So perhaps a rose route is unnecessary. But just wanted to make sure!

Context
I’m trying to apply the general task naming conventions in a (non-UM) suite, and for purposes of clarity/my sanity, have just ended up changing some app names from my original, more succinct choices to longer ones which more properly describe what’s going on, to help me visually parse & understand the graph / suite.rc file. So I’ve gone from:

  • model_test_cold > model_config-compile-test_cold
  • model_compile_cold > model_config-compile_cold

(the apps wrap some 3rd-party makefiles for 3rd-party model. Makefiles only expose the config-compile-test and config-compile options. I prefer not to delve into innards, to expose the individual config, compile, and test components, as I don’t want to shoulder maintenance burden if/when innards change)

However, these new names, while more explicit, are much longer, and go ~against the “keep names as short as possible” guidance. Hence keen to see what other options I could use for purpose, allowing terser names for the apps/tasks (e.g. a cryptic model_cfg-cpl-tst_cold!)

2

Thanks for raising this question, sadly it is a slightly awkward one to answer.

Personally my inclination to docs would be:

  • Information pertaining to apps should live inside the app so as to enable them to be more portable and self-contained.
  • It’s a good idea to keep the docs with the thing they are documenting, save the documentation is not kept up to date and becomes more hinderance than help.

Both Rose and Cylc provide means to document different things. It would be good to have some discussion and input over documentation to help guide the development of Cylc8 and Rose2 which should be able to go much further than the current systems in this respect.

Documentation In Rose & Cylc

Here’s a quick review of what’s currently possible in Rose2019 & Cylc7.

Rose Configurations

App Comments

In rose config files comments are associated with configurations, sections and inputs.

# app-level doc

# section-level doc
[env]

# input-level doc
foo=bar

You can see how comments are associated by loading the configuration in using the rose.config Python API:

$ PYTHONPATH="path/to/rose/lib/python" python2
>>> from rose.config import load
>>> n = load('rose-app.conf')
>>> n
{'state': '', 'comments': [' app-level doc'], 'value': {'env': {'state': '', 'comments': [' section-level doc'], 'value': {'foo': {'state': '', 'comments': [' input-level doc'], 'value': 'bar'}}}}}

The rose edit GUI presents input-level comments next to the input name with a hash symbol, however, other comments are not used.

rose-edit-screenshot

The next iteration of the Rose GUI could potentially make use of these comments.

We exploit these comments within Rose to auto-document the site/user configurations from an example file using the reStructuredText markup language. This system comes in the form of a Sphinx plugin and could be used to document other configurations in the same way.

These comments have their uses, however, in Rose it makes more sense to provide documentation in metadata. They are likely more useful for explaining values within a configuration e.g. “I set this to x because of that”.

These fields are not available at the app level.

Configuration Metadata

Within configurations it makes sense to use Rose metadata to document things. This enables centralised metadata and separates the application model from its configuration.

Here’s an example of application metadata:

title=app title

[env]
title=section title

[env=foo]
title=input title

And here is how that shows up in rose edit:

Screenshot from 2021-01-25 10-26-47

Again the application-level entry has no effect, however, the section and input level titles are displayed in the place of the default titles.

This also applies for suite configurations which are handled in the same way, so technically you can configure a suite title and description in the metadata, however, this will not be used in the GUI (as far as I’m aware!).

Rosie

At the suite level there is the rose-suite.ini file which is used to provide the information for the rosie suite discovery and management tools.

This file provides title and description (amongst other things).

Documenting Cylc Workflows & Tasks

Cylc provides a [meta] section both at the workflow and task level e.g.

[meta]
    title = 'workflow title'
[runtime]
    [[task]]
        [[[meta]]]
            title = 'task title'

You have title and description fields as in Rose, however, Cylc also allows the configuration of arbitrary metadata which allows you to configure things like this:

[runtime]
    [[foo_abc]]
        [[[meta]]]
            system = 'foo'
    [[bar_abc]]
        [[[meta]]]
            system = 'bar'

These fields are also available to Cylc event handlers.

Currently Cylc metadata has limited use in the Cylc GUI, however, with Cylc8 there is potential for this use to be greatly expanded.

Thinking Forward To Cylc8 & Rose2

At the moment both system support something but neither provides a particularly universal means for effective documentation so my advise would be use what works best for you.

As both the Rose and Cylc GUIs are to be re-developed there is potential to change the way documentation is used in both systems.

Cylc8 should make much more use of metadata then Cylc7, here are some ideas I’ve considered so far:

One possible option is that Cylc could detect when a task is configured to run a Rose app and load in associated Rose metadata at suite start. For example this copy the Rose app title/description to Cylc metadata items called “rose-app-tiitle” and “rose-app-description” which could then be displayed in the Cylc portion of the GUI.

Now to chuck in the problem of documenting template “things” vs documenting the usage/configuration of the “thing”:

  • For example some suites are more like templates, their documentation may reflect their general purpose, but only when the suite is configured and installed does it assumes a more specific purpose. In these cases the Rosie metadata is better for recording the general purpose and the Cylc metadata better for recording the usage. These suites may even use Jinja2 to set the Cylc metadata based on values in the Rose configurations.
  • Same applies to Rose applications where an app could potentially be used and configured in different ways (e.g. using env vars, command keys or optional configs) so it may make more sense to document the use of the app in Cylc and the internals of the app in Rose?

Comments / ideas welcome, though be aware that many features may come in later Cylc 8 releases (we can’t do everything in Cylc8!).

2 Likes
3

Fantastic, thanks very much for the comprehensive reply Oliver - v helpful for understanding. And good as ever to see the wide range of use-cases/approaches you all support - doesn’t make this easy!

Thanks for the points on rose options - was partly concern about divergence of doc/code which was driving my “can I do this in rose?” question - like you, think having this local can maybe help diminish risk a little!

I didn’t know/forgotten about the possibility of using comments in rose config files - think I’d seen the input-level doc demo’d in tutorials, but had forgotten. And certainly wasn’t aware of the app/section-level comments-as-docs. Nice to see your reST examples to see how this might be combined with markup for richer docs.
I’d also not twigged that the configuration metadata items (title, description etc) could apply to levels above input (i.e. also in app, section).

For my use-case & apps, for now, I’ll probably aim mostly to document via the higher-level configuration metadata (title, description too?)
will use app comments only if necessary (e.g. if description not possible) - this simply as the title/description metadata label helps give context on purpose of following text. Also to avoid the visual noise of hashes-in-docs
Think this will accomplish my main aim of ~discoverable docs, co-localised with relevant app (to avoid de-sync over time).

I like your future ideas, especially the cylc-detects-and-loads-rose-metadata. Seems to keep responsibilities in the right place (as close to encoded/configured specific purpose as possible), while enabling higher level exposure of docs, and discoverability that they exist at all.

I guess my only query would be around mechanics of this.
In some ways having to write explicit loading boilerplate code in suite.rc to allow this might be helpful-if-slightly-irritating:

[runtime]
    [[task]]
        [[[meta]]]
            # fetches any app metadata defined {title, description, etc}
            # and exposes these defined fields in suite.rc.processed
            rose get-metadata

Helpful as gives a visual hint to someone reading suite.rc (e.g. browsing a repo, performing a review, …) that metadata is available, and (if familiar with mechanics) that can click through to app to see it / run suite and look at suite.rc.processed

Irritating as why should this line have to be present for every rose app, when retrieval could be fully automated!
But then no hint that “this app contains docs intended to help readers understand its purpose”.

Perhaps such a hint in suite.rc should be unnecessary - maybe there are cleverer ways to help someone looking at a suite[.rc] determine “what is this collection of apps/this app doing?”.
Might simply be encouraging culture of “document your app” (i.e. comply with guidance on rose metadata)? Possibly helped/enforced by a linter (“have you forgotten to document your app’s metadata?”)? Apologies if rose macro --validate already does this!

1 Like
4

This isn’t something we have really given thought to yet. The possibility I was describing which may or may not be a good idea, is to have Cylc load a plugin from Rose which processes each task. If the task calls a Rose App (as determined from the script) then load the metadata and insert it into the Cylc [meta] section on the fly. It’s ugly and could have a performance cost but could work.

I’ll add this to the agenda of a future Cylc developer meeting and see what we come up with.

1 Like
5

thanks for the awesome information.