genroc

    docs / Guides / Process definition

    Versioning

    Learn about versions and channels

    Genroc compares new definitions to the previous ones and if it's a new one automatically bumps up the version.

    > genctl apply
    latest: hello v1 -> v2 (new)

    Commands are assuming definitions glob in .genroc. If you don't have that, you can use -f to specify definition file(s).

    Definitions are compared as a normalized json. If you apply an already existing version it's not duplicated but reused (so the version can also go down if you revert a change). The json is the definition as you wrote it, so changing an x- key, or rewriting retry: 3 as retry: { retries: 3 }, is a new version. Apply says when nothing that runs changed:

    > genctl apply
    latest: hello v2 -> v3 (new, same runtime as v2)

    Instances on v2 behave exactly as they would on v3, and genctl upgrade moves them over with nothing to reconcile.

    > genctl apply
    latest: hello v2 -> v1 (existing)

    An apply moves a channel pointer, so that move is what the line reports. new minted a version, existing matched one already stored — which is how a revert lands, with nothing written and latest walked back to v1. A re-apply that moves nothing reads (current), and - stands in for a channel that had no pointer yet.

    Channels

    Genroc uses release channels, by default latest is used, but you can specify which channel you want to apply.

    > genctl apply --channel test
    test: hello - -> v3 (new)       # v3 version doesn't influence latest

    The very first apply of a process sets latest too, whichever channel you name.

    To start the process you can specify the channel or the version:

    > genctl run hello --channel test
    started: 8nte1end  hello@v3  (running)
    # or
    > genctl run hello --version 1
    started: 6nnmhxnv  hello@v1  (running)
    # or
    > genctl run hello
    started: 77fg90c5  hello@v1  (running)

    You can list all the channels for given process like this:

    > genctl channel list hello
    latest -> v1   moved 23m ago by ...
    test -> v3   moved 11m ago by ...

    Channels are intended for beta versions or internal testing before release, so you can push your definition to test channel, try if it works and then just update the latest channel to the same version:

    genctl channel promote --from test --to latest --process hello

    Without --process, promote moves every process the test channel points at.

    Child/parent versioning

    By default, you don't have to specify which version of the child the parent wants to use; genroc will assume you want the one from the same channel.

    On apply, genroc decides which version of the child the parent will use, and bakes it into the saved definition.

    > genctl apply
    latest: child v1 (current)
    latest: parent v2 -> v3 (new)

    Here the parent@v3 will always use child@v1. If we change the child and apply both, the parent definition changes as well, because the version is part of the definition comparison.

    > genctl apply
    latest: child v1 -> v2 (new)      # only child was changed
    latest: parent v3 -> v4 (new)     # parent was updated automatically

    Applying only the child leaves the parent on the old version. genctl channel status lists parents like that, pinned to a child version the channel no longer points at.

    Explicit version

    You can also explicitly specify which version you want to use in the child action.

    ...
    tasks:
      - id: greet
        action:
          type: child
          name: welcome
          version: 2

    This will opt out from genroc automatic version resolution.