Support mutation M.M-1

[eedugon]

We need this functionality to keep track of the versions supported by default on Elastic Cloud Hosted, which are:

• The two latest minor versions of the latest major version
• The latest minor version of the previous major version

This PR focuses on the first item.

I'd like {{version.stack | M.M-1 | M.M }} to render to 9.1 if version.stack is for example 9.2.3.

If minor version is 0 we return the original value without deducing anything, to avoid a negative number.

PS - I've used cursor to implement this.

This functionality would be required by elastic/docs-content#4607

[github-actions]

🔍 Preview links for changed docs

• docs/syntax/substitutions.md
• docs/syntax/version-variables.md

[reakaleek]

LGTM 🚀

But let's wait for @Mpdreamz feedback because he has all the context about this feature.

[Mpdreamz]

Might as well implement decreasemajor? :)

[eedugon]

Not sure about the use cases or benefits, but we can easily implement it, yeah. I'll add it to the PR.

[eedugon]

Added to the PR. We'd return 8.0.0 now no matter what 9.x.x release we are currently in.
In the future, whenever we are on 10.x.x it would return 9.0.0.

If major is 0 (0.y.z) it would return the original value, same as with the M.M-1.

As soon as we decide what exactly to return in these corner cases I will adapt the PR.

[Mpdreamz]

Aye thats what i was thinking!

[reakaleek]

If minor version is 0 we return the original value without deducing anything, to avoid a negative number.

Actually, I think we should error if the user tries to decrease a 0 minor version.

[eedugon]

Actually, I think we should error if the user tries to decrease a 0 minor version.

I thought about that, but I thought it was a bit risky considering this is dynamic... in the future whenever 10.0.0 is released we don't want our docs to fail building because M-1 starts failing, or? Maybe indeed we want :) but then we should change the docs until 10.1.0 is released....

I was doubting between returning an empty string or the original value. If you think it's better to return an error that's totally ok.

[Mpdreamz]

I agree it's better to anchor it to 0 and dont return an error.

[reakaleek]

I agree it's better to anchor it to 0 and dont return an error.

In the worst case this will show an incorrect version and we won't even be aware of it.

[eedugon]

I agree it's better to anchor it to 0 and dont return an error.

@Mpdreamz , do you mean to normalize it to 0 in a similar way than the +1 operations?

So, instead of returning the exact original value:

• 9.0.3 --> M.M-1 --> 9.0.0 --> Is that what you propose? I'm totally ok with that too, as it will be a bit more aligned with M+1 that always returns .0s after the affected item.

In such case I'd do M-1 in a similar way:

• 0.2.3 --> M-1 --> 0.0.0 (something that shouldn't be used unless your system has released 0.x and 1.x versions already).

Did you mean this approach or do you prefer to return the "original value" in these special cases?

[Mpdreamz]

The two latest minor versions of the latest major version

Supported range is
* {{version.stack | M.M-1 | M.M-1 | M.M }} to {{version.stack | M.M }}

This would render

version.stack	result
9.0	9.0 to 9.0
9.1	9.0 to 9.1
9.2	9.0 to 9.2
9.3	9.1 to 9.3

Is that an error or acceptable? I am not sure its an error @reakaleek, wether its acceptable I'll defer to the writers @eedugon @elastic/docs-tech-leads

The latest minor version of the previous major version

This relates to: #2111

@eedugon can you discuss this with @shainaraskas ?

[reakaleek]

The two latest minor versions of the latest major version

Supported range is
* {{version.stack | M.M-1 | M.M-1 | M.M }} to {{version.stack | M.M }}

This would render

version.stack result
9.0 9.0 to 9.0
9.1 9.0 to 9.1
9.2 9.0 to 9.2
9.3 9.1 to 9.3
Is that an error or acceptable? I am not sure its an error @reakaleek, wether its acceptable I'll defer to the writers @eedugon @elastic/docs-tech-leads

The latest minor version of the previous major version

This relates to: #2111

@eedugon can you discuss this with @shainaraskas ?

What would happen if we were at 10.0?

[Mpdreamz]

version.stack	result
10.0	10.0 to 10.0

[reakaleek]

version.stack result
10.0 10.0 to 10.0

Yes. But is this the expected value? Shouldnt it be 9.x.x? Probably depends on the context.

But IMO, this leaves too much space for unintended versions.. and if we just use a fallback to 0, no one will ever know until someone complains.

[Mpdreamz]

Ahh no

{{version.stack | M.M-1 } should never mean decreasing into the previous major that should be explicit with {{version.stack | M-1 } or using the previous version variable if we end up supporting it with #2111

To me thats the path of least surprise.

[reakaleek]

I think a compromise would be to create a hint in the case we need to fallback to 0.

IMO, the fallback can lead to unexpected version rendering
and a wrong version has worse consequences than a build error. But with a hint are at least aware of it.

P.S.

IMO we should also document the behaviour

[eedugon]

@Mpdreamz , your formula is OK, but it's not the formula I need to use:

Your formula:

{{version.stack | M.M-1 | M.M-1 | M.M }}

That's actually a -2 and renders ok as you explained in #2454 (comment)

But I'm going to use

{{version.stack | M.M-1 | M.M }}

Because I only need -1. The latest TWO minors of latest major are the CURRENT and M-1, not M-1 and M-2.

Anyway I'd say it's all OK.

Is that an error or acceptable?
It's acceptable for the use case you have shared, which is not mine. Mine is described in this comment :)

[eedugon]

@reakaleek , the behavior is documented

Do you mean in the code? THere's only one line with the payload and at the moment it's pretty simple:

SubstitutionMutation.DecreaseMinor => TryGetVersion(value, v => v.Minor == 0 ? value : $"{v.Major}.{v.Minor - 1}.0"),

We need to clarify if it's ok to return the original value when -1 does not exist, or if we should normalize the original value with .0s also. For example for 9.0.1, M-M-1 could return 9.0.0 instead of the original value.

Whatever you prefer (cc: @Mpdreamz )

[shainaraskas]

Sorry to come into this late - I am having trouble making heads or tails of what's happening here. however, if my understanding is correct, I think we should:

• backstop to 0 for the minor and patch segments
• error on 0.0 (major = 0 minor = 0) - if it never makes it into the codebase as 0.0, it shouldn't silently fail later.

this is going to be a very infrequently used variable so I don't think we need to consider the edge cases super thoroughly, though.

[lcawl]

I agree we'd want to avoid silent failure when crossing major version boundaries and the "10.0 to 10.0" example in #2454 (comment) seems like something we'd want to catch.

I haven't touched any of the version config files in the new system yet, but from perusing https://github.com/elastic/docs-builder/blob/main/config/assembler.yml and https://github.com/elastic/docs-builder/blob/main/config/versions.yml this makes me wonder if we'll eventually need "previous" values alongside those "current", "next", and "base" values, like we used to need in https://github.com/elastic/docs/blob/master/shared/versions/stack/master.asciidoc

[eedugon]

@lcawl , we need this if we want to be able to write an example of this:

Elastic Cloud Hosted makes available the following versions:

• The two latest minor versions of the latest major version
• The latest minor version of the previous major version

The previous, if we want to show it with an example, would need this functionality.

But of course we can write a static example and forget about showing the latest 2 minors dynamically.