Automate bumping doc versions

[debadair]

Currently, bumping doc versions for a release is a manual process that requires updates in multiple repos. We also have to update the version attributes when new branches are cut. It's easy to miss a step or fat-finger a change and end up with bad links that we either don't know about or that end up breaking the build weeks later.

We can do a couple things to make this easier & less error prone:

• Isolate the doc version related attribute definitions for each product in separate files. These version files should live in the docs directory for each product. That way, they're versioned along with the rest of the docs and you don't have to go hunting in a separate repo to see what your doc version is set to. Elasticsearch and Beats already do this. We need to move the Logstash version attributes out of the index file & update X-Pack and Kibana to use local version files instead of the shared files in the docs repo.

• Create a script we (anyone) can use to bump the versions. The script should allow bumping the versions in all of the repos, or just selected repos. Something like: bump-versions --branch 5.6 --version 5.6.4 --repo all bump-versions --branch 6.x --major 6.x --version 6.1.0 --state unreleased --repo logstash

[dedemorton]

@tsg Just an FYI that we'd like to make the version bumps easier (hoping to do this after 6.0). Do you know if we still use the version.asciidoc outside of the docs? I seem to recall that we had a code dependency on this file (it wasn't used strictly for docs), but I can't remember how the file was used or if we still have the dependency.

[tsg]

Yeah, we do that for example to create the Kubernetes manifest files. We want them to match the docs version instead of the software version (because they get bumped at different times).

As long as version.asciidoc is kept simple enough, we can probably parse it for our needs, and it sounds like this issue has the same goal. If not we can figure something else for our needs.

Btw, I still think my proposal here that each project provides a script to bump the docs version has advantages. For example, we might want to write the version.asciidoc file, but also an extra YAML file to be used in the software. I suspect Kibana is going to need something like that for the Home project as well.

[debadair]

Most of our docs now use the shared stack versions: https://github.com/elastic/docs/tree/master/shared/versions/stack.

@dedemorton It looks like Beats is still an outlier?

@nrichers What about Cloud?

Having one place (docs/shared/versions/stack) to update makes adding versions pretty easy, so not sure how important automating it is any more?

[dedemorton]

Beats is using the shared version file for docs, but we do need to bump the version for other reasons (the go files use the version info, too). AFAIK, that's not changing.

[dedemorton]

@bmorelli25 I think APM is in the same boat as Beats, right?

[bmorelli25]

@dedemorton It might be worth looking into again. In the APM Server reference we were able to remove the dependency on the docs for Beats versioning.

[nrichers]

@debadair Elasticsearch Service, Elasticsearch Add-On for Heroku, and Elastic Cloud Enterprise all use one of the versioned files in shared/versions/stack/, though we could try using shared/versions/stack/current.asciidoc. I'll open a PR in master.

Elastic Cloud on K8s uses shared/versions/stack/current.asciidoc, so no change needed.

Elastic Cloud Control really only cares about the version of the ECE API and soon the ESS API. If that every changes, we should do what ECK does.

(Generally, all Cloud docs have been using the shared versions and attributes files for some time, with the exceptions noted.)