Generate changelog YAML files for ML?

[pugnascotia]

I'd like to explore how we could generate changelog YAML files for ML, in a similar manner to what we now do for Elasticsearch. Right now, the ES parts of the notes can be completely generated from the YAML files, but we then have to manually merge in the ML-specific parts. It would be ideal if the notes could be generated with no manual intervention, bar curating the contents of the YAML files themselves.

It would be a simple matter to tweak the existing HOMER support to output ML-specific asciidoc (i.e. the {ml-pull} links), and the workflow would be very similar to ES:

flowchart LR
D([Dev]) --> |Raises| P[ml-cpp PR]
P --> |Notifies| H[Homer]
H --> C{Create or update\nchangelog?}
C -->|No| Ig([Ignore])
C -->|Yes| Cr[Create or update]
Cr --> Y[/"docs/changelog/5432.yaml"/]
Y -.-> P

Loading

We would then need a convention for how the ES build pulled in the YAML files from outwith the repo. We could require the ml-cpp repo to be checked out alongside the elasticseach repo:

flowchart LR
subgraph elastic/elasticsearch
EsC[ES Changelogs] -.-> EsB[ES Build]
EsB --> |./gradlew generateReleaseNotes| R[/Release notes/]
end

subgraph elastic/ml-cpp
MLC[ML Changelogs] -.-> EsB
end

Loading

Or we could pull the ML changelogs directory from the GitHub API:

flowchart LR
subgraph elastic/elasticsearch
EsC[/ES Changelogs/] -.-> EsB[ES Build]
EsB --> |./gradlew generateReleaseNotes| R[/Release notes/]
end

subgraph GitHub
MLC[(ML Changelogs)] -.-> |HTTP GET| EsB
end

Loading

Arguable the current docs/CHANGELOG.md file would become redundant if we adopted some form of the above. We could replace its contents with a point to the online docs, like ES has done.

[droberts195]

Arguable the current docs/CHANGELOG.md file would become redundant if we adopted some form of the above.

Yes definitely. It's not published. It only exists as a place for people to type release notes for inclusion into the ES release notes. If we use separate YAML files per PR instead then we can definitely get rid of it.

(This file is basically using the process that Elasticsearch used for a while starting with elastic/elasticsearch#29450 and ending with elastic/elasticsearch#30593.)

It would be a simple matter to tweak the existing HOMER support to output ML-specific asciidoc (i.e. the {ml-pull} links)

One thing to consider is what to do if a change spans both elasticsearch and ml-cpp. Currently we handle this by marking the ES PR >non-issue but referencing both the {ml-pull} and {es-pull} in the changelog that's in the ml-cpp repo.

ml-cpp/docs/CHANGELOG.asciidoc

Lines 229 to 230 in 91be7ef

	* Add a response mechanism for commands sent to the native controller. (See
	{ml-pull}1520[#1520], {es-pull}63542[#63542], issue: {es-issue}62823[#62823].)

The final thing I would say is that it doesn't take that much time per release to manually paste over the ML release notes into the ES repo. I would be wary about spending weeks working on a convoluted automated process that takes years to pay back in time saved, especially if there's a risk it could sometimes fail and still need manual intervention to sort out.

[pugnascotia]

The final thing I would say is that it doesn't take that much time per release to manually paste over the ML release notes into the ES repo. I would be wary about spending weeks working on a convoluted automated process that takes years to pay back in time saved, especially if there's a risk it could sometimes fail and still need manual intervention to sort out.

Absolutely, I'm fine if the outcome of this issue is "we're not going to do anything", so long as that's a conscious decision. That said, I think I could have something working inside a week, especially if I don't try and use the GitHub API.

[droberts195]

I think we'll have to do something about this after all. The current process actively deletes ML release notes that were manually added for previous releases from the overall list - see elastic/elasticsearch#85190 for example.

[lcawl]

I have not closely examined this project, but I see that multiple documentation output pages (e.g. https://www.elastic.co/guide/en/elasticsearch/reference/8.1/release-notes-8.1.1.html and https://www.elastic.co/guide/en/elasticsearch/reference/8.1/release-notes-8.1.0.html) are being generated from a single source file (e.g. https://github.com/elastic/elasticsearch/blob/8.1/docs/reference/release-notes/8.1.asciidoc). From a docs point of view, I don't think there are any benefits to this design. And it seems to run the risk of over-writing any manual changes we made. In general, I try to have a 1:1 mapping between source and output pages. Is it possible to change the process so that there's a single new file generated for each release page?

[pugnascotia]

@lcawl We can certainly do that - do you want to raise an issue in elastic/elasticsearch that describes what you want to see?

[lcawl]

I've created elastic/elasticsearch#85250 but if I've explained poorly or you want more info, just let me know!

[pugnascotia]

@droberts195 elastic/elasticsearch#85279 should ameliorate the worst of the ML changelog deletions, though obviously doesn't completely fix ti.

[lcawl]

It seems (based on elastic/elasticsearch#87092 and the fix in elastic/elasticsearch#87135) that the highlights are also now generated and the ML content I re-added will be overwritten (with whatever exists in the yaml file?) when the next release goes out. I think this also implies that if we ever (manually) add a highlight related to an ml-cpp issue, it will be completely ignored and overwritten when the next release occurs.

[lcawl]

I think if we decide to generate changelog YAML files for ML, it should ultimately relate to https://github.com/elastic/cloud/issues/83993