EDU-3794: add information on how to use the TemporalChangeVersion SA

[antmendoza]

Issue link: https://github.com/temporalio/documentation/issues/3285

Brief description

https://docs.temporal.io/visibility#default-search-attributes mentions that there is an SA called TemporalChangeVersion, but it does not mention how to use it.

Your recommended content

I would like to see a short description of how to use it, like we have with BuildIds

The SA value is stored with the following format: changeID + "-" + version

given this code

v := workflow.GetVersion(ctx, "addActivity", workflow.DefaultVersion, 1)

if v == 1 {

    var result string
    err := workflow.ExecuteActivity(ctx, Activity, name).Get(ctx, &result)
    if err != nil {
       logger.Error("Activity failed.", "Error", err)
       return "", err
    }

}

The query that returns the workflow execution with this version will be

TemporalChangeVersion="addActivity-1"

Thank you

[antmendoza]

Regarding " .. if the GetVersion API is enabled". I believe it is enabled by default and can be used (except for Java https://docs.temporal.io/develop/java/versioning#adding-support-for-versioned-workflow-visibility-in-the-event-history). I could be wrong

[fairlydurable]

Thanks for submitting this and providing the sample code. Can you recommend a subject matter expert about the GetVersion API?

I will note as well that we have a ton of tickets and work to revamp visibility coverage. This is a great addition, and I'll add it to the epic.

[axfelix]

To the absolute best of my knowledge, all of our patching APIs (including GetVersion in Go and Java) have been enabled out of the box for some time -- I did a bunch of work on Versioning documentation for the course a year ago and there is no need to enable anything here. But it is true that you need to manually upsert a search attribute in Java to be able to query versions, since the Java SDK doesn't do that for you.

[joshmsmith]

FYI this is now possible to enable in Java - it no longer has to be manually upserted.
Docs still need to be updated.