Op Rework - sakura-team/sakura GitHub Wiki

• code_ref: it is a reference in a git repository, such as branch:master or tag:v3.2. Note that this reference may move over time (e.g. unless a project is dead, its master branch usually moves on), unlike a commit_hash.
• revision: it is a fixed point in git history (linked to a commit_hash).

• In sakura's "Operator" page (considering the "Operator" tab is no longer greyed out), the user clicks on + at the bottom of the list of operator classes (how to print this list is described in the next section).
• The user fills in a form:
  • code URL (URL of the repository)
  • code sub-dir (default "/"), greyed out until code URL has been validated
  • label default revision:, with a hourglass for now (will be replaced by a combobox when values are available)
• asynchronously, as soon as the user has filled in the code URL:
  • call sakura.apis.hub.misc.list_code_revisions(code_url).
  • hub returns a list of triplets. 1st value is branch:<name> or tag:<name>, 2nd is the commit_hash, and 3rd is not used for now (it will be useful below). Example: [("branch:master", "abcdefabcdef", ""), ("tag:v3.2" "eeeeeeffffffff", "")]
  • the hourglass is replaced by a combobox filled with these values. We may actually just print the 1st value (commit_hash is not really useful because we propose only the last commit of a given branch at this time). The values of the combobox would just be branch:master and tag:v3.2 in my example.
• The user validates the form. This causes:
  • a call to API: sakura.apis.hub.op_classes.register(code_url, default_code_ref, default_commit_hash, code_subdir), with, for example, default_code_ref="branch:master" et default_commit_hash = "abcdefabcdef".
  • When the call returns, we refresh the list of operator classes (or we just add the new list item).

This defines the content of the "Operator" tab, in GUI top menu, that was greyed out up to now.

• call sakura.apis.hub.op_classes.list() and print each operator class item, with:
  • some metadata (op_cls.name, op_cls.short_desc, op_cls.code_url, etc.)
  • default revision:
    • for the developer (to be precise, it is the owner, the user who has declared the operator class, as described above), he gets a combobox with:
      • the current value, pre-selected in the combo, given by op_cls.default_code_ref and op_cls.default_commit_hash. For example: branch:master @abcdefabcdef (current)
      • button others.... If user clicks on it:
        • call sakura.apis.hub.misc.list_code_revisions(code_url, { reference_cls_id=<cls_id> }). This is the same call as above, except that we indicate to the hub the operator class we are acting on, in order to let it return annotated entries.
        • the hub returns triplets again, but this time we will checkout the 3rd value which is an annotation. For example if branch:master moved on upstream, it will indicate it by returning ("branch:master", "cccccddddddd", "(HEAD, newer)"). GUI will fill in the combobox by concatenating the 3 fields (for example "branch:master @cccccddddddd (HEAD, newer)"). Of course, hub will also return values of other branches or tags, values will be sorted, and include the current value (1st entry). As a result GUI can really overwrite the full content of the combobox.
        • if one of the other values (others...) is selected, then:
          • call sakura.apis.hub.op_classes[<cls_id>].update_default_revision(code_ref, commit_hash), with for example code_ref="branch:master" and commit_hash="cccccddddddd"
          • when the call returns, update this entry of the list of operator classes by calling sakura.apis.hub.op_classes[<cls_id>].info()
    • Other users can only visualize the current value (they get a label instead of the combobox), for example "branch:master @abcdefabcdef".

Note: the trick about button others allows to limit heavy processing: list_code_revisions() takes more than half a second to run, so we cannot afford to do it for all involved code repositories.

When backend has to instanciate an operator, here is how its revision is computed:

• if the user has already instanciated other operators of this class, and all these operators run the same revision, this revision is selected.
• otherwise we select the default revision for this operator class (op_cls.default_commit_hash, selected with the combobox of the section above).

In Code tab, above the source edit area, we add a label revision: with a combobox allowing to update and reload the source code. Similarly to the case of the operator class, it contains the following values:

• the current value, preselected in the combo, given by op.code_ref and op.commit_hash, for ex. branch:master @abcdefabcdef (current)
• button others.... If user clicks:
  • call sakura.apis.hub.misc.list_code_revisions(code_url, { reference_op_id=<op_id> }). Same as above, but this time we specify the operator instance, not its class.
  • the hub returns annotated triplets, again. In particular, if the default revision for this class of operators is different from the current revision (for example in the case where the developer pushed a fix), the hub will return this entry with annotation "recommended".
  • if one of these values (others...) is selected, then:
    • ask the user (with a small modal window) whether he wants other instances of this class to be updated to the selected revision, or just this one.
    • call sakura.apis.hub.operators[<op_id>].update_revision(code_ref, commit_hash, all_ops_of_cls=[true|false]), with for example code_ref="branch:master" and commit_hash="cccccddddddd"
    • when the call returns, call the code to re-display the operator modal window, and preferably return to Code tab.

When the user request a revision change, the backend must do it, but it will also have to reload this operator instance (unload python modules involved, then re-import).