Formalize/document process for providing Fleet and Elastic Agent release notes

[dedemorton]

We've been building the Fleet and Elastic Agent release notes by hand since version 7.13, but we need to formalize a process and start generating release notes.

02/15/2023 Edited to make this description more relevant.

[dedemorton]

@ph @jen-huang Do we want to tackle this for 7.14, or continue to update the relnotes manually?

[dedemorton]

@andresrc We need to sort out some automation for generating release notes for Fleet and Elastic Agent. Maybe this should be a dev issue instead of docs?

[dedemorton]

@andresrc Are there any updates on the release notes process? I'd like to stop doing this manually or get the development team to own the updates because it keeps slipping through the cracks for patch releases.

[dedemorton]

@cmacknz I am reviving this discussion because I've been doing the Elastic Agent release notes manually for quite some time now. It involves me picking through the changelog each release, comparing it to the commit for the build candidate, and copying (plus editing) the list of Elastic Agent changes into the release notes published under https://www.elastic.co/guide/en/fleet/current/release-notes.html. I also copy the Fleet-related release notes from the Kibana docs so that they are in one place for Fleet and Elastic Agent users.

I know you've been working on Beats release notes, and I wonder if we can start following a similar process. We also need to decide if duplicating the Fleet release notes in the Fleet/Agent documentation makes sense (rather than pointing to the Kibana docs). (TBH, I was really hoping that we would have some kind of consolidated release notes by now so that users would see all the stack-related release info in one place, but that hasn't happened yet because no one is leading the effort AFAIK.)

I'd like to arrive at some kind of automated system (or at least have someone from the dev team on the hook for these release notes).

@ollyhowell I'm marking this as a to-do on our project board because it's been in the backlog for too long.

[cmacknz]

We are planning to use a new process for the agent release notes starting in 8.5.0 using https://github.com/elastic/elastic-agent-changelog-tool. The first PR is here elastic/elastic-agent#1244.

@andresrc can provide more details the tool itself, but it should remove the need to manually pick out the changes that should be published from the agent changelog.next file.

[andresrc]

@dedemorton we are using 8.5.0 as a pilot we will send more details during the FF period.

[dedemorton]

I'm going to leave this open to make sure that the new process is communicated to the writing team once we have things nailed down.

[dedemorton]

@cmacknz Just wanted to check in with you on a few questions related to the Elastic Agent/Fleet Server release notes.

• Are we still planning to roll out the new process for 8.6?
• Will the new release notes include Fleet? If not, we should point to the Kibana release notes because users are accustomed to seeing a consolidated view of all release notes that impact Elastic Agent, Fleet Server, and Fleet (for example, see the release notes for 8.5).
• What will the process look like for 8.6 (assuming that's our target)?
  • Who will be run the elastic-agent-changelog-tool and open the release notes PR?
  • Will someone on the writing team edit the fragments or the generated release notes? When?
  • What else do we need to consider?

[cmacknz]

Are we still planning to roll out the new process for 8.6?

We are planning to keep using the elastic-agent-changelog tool in the elastic-agent repository for 8.6

Will the new release notes include Fleet?

We've only changed the process for the elastic-agent repository, so no.

Who will be run the elastic-agent-changelog-tool and open the release notes PR?
Will someone on the writing team edit the fragments or the generated release notes? When?
What else do we need to consider?

We're open to suggestion on this. I think what makes the most sense is for the development team to make sure that the changelog fragments are correct, and can generate a valid changelog. The writing team is then responsible for creating the changelog PR and editing the content as needed.

For timing usually the final BC being generated is when we try to generate and cleanup the changelog. It is a lot easier to notice the addition of new changelog fragements though, so we could try to start the process earlier if it would be helpful.

[cmacknz]

We are still figuring out how to manage and enforce the creation of changelog entries. In particular we need some automation to delete the fragements once the release has happened.

[dedemorton]

@cmacknz We need to sort out the release notes process.

For the 8.6.x release notes, it's probably better for users if we continue to assemble the content manually so that it is consistent with other 8.6.x release notes. Right now, your release process document is a little vague about how that happens for Agent/Fleet relnotes. That document needs to be clear about who is doing the manual work and what needs to be done.

For 8.7, though, it would be really good to get this process fully automated. We need to have a plan for what the new release notes content will look like. Ideally, at some point, your team should "own" the release notes and just ask the writers to review them. Some thoughts:

• I don't think we should continue to provide Fleet release notes by copy/pasting them into the release notes document. We should probably send users to the Kibana release notes for the list of Fleet changes.
• We'll need to continue providing release notes for Elastic Agent and Fleet Server. Those release notes should be generated by the development team.
• We need to decide the best way to present the changelogs to users. The "container" topic for the release notes will need to be rewritten, and we'll need to figure out the best way to pull the files you generate into the docs.

cc'ing @elastic/ingest-docs for awareness.

[dedemorton]

Sorry I think I should have pinged @pierrehilbert on my question.

[pierrehilbert]

According to me, the best solution would be to migrate beats on the new changelog solution too and to change the current pipeline to consolidate ascii doc from each repository.
What do you think?

[cmacknz]

I definitely think the changelog consolidation step for the Elastic Agent should be triggered by the Beats changelog job (or another similarly named new job): https://beats-ci.elastic.co/job/Beats/job/Release/job/beats-release-changelog/

We need automation to generate the YAML changelog summary in the agent repository and also delete the changelog fragments that are no longer needed. I would set this up before we migrate Beats to make sure we get it working properly.

[dedemorton]

We need automation to generate the YAML changelog summary in the agent repository and also delete the changelog fragments that are no longer needed

@cmacknz Will the automation work happen in time for 8.7? Do we want to change the format of the published release notes to work better with your automation? Based on the responses to my questions, I'm not sure when the dev team will take over ownership of the release notes or what the writing team needs to do to support you for 8.7 and later.

I'll continue to hack together the 6.8.x relnotes until that's no longer required.

[karenzone]

Related: https://github.com/elastic/elastic-agent-changelog-tool
Related work: elastic/elastic-agent#2584
Thank you, @pierrehilbert.

Is there an issue or meta-issue in the elastic-agent repo where we can identify next steps and track this work?
Another option: We can relocate this issue to the elasticagent` repo for tracking.

Goals:

• Automated process with tooling to support
• Democratize the process to remove dependencies on a single person or subset of people.
  • Anyone on the team should be able to click the button after FF to generate content.
  • Manual intervention required to get finished release notes should be minimal. Ideally, just review, approval, merge, and backport if needed.
• When we've made this automated and easy, make generating/merging release notes part of rotating Fleet/Agent Release Manager responsibilities.

Next steps

• What would it take to get snippets output to asciidoc format in a DRAFT PR?

[karenzone]

Related: #200

[pierrehilbert]

Hey @karenzone,
I'm out during next week but is it okay for you if we plan a meeting together when I will be back to be aligned on next steps and of what would make this changes a success from your point of view?

[karenzone]

Thank you, @pierrehilbert. I'm out the following week, but will set something up when I return.

[dedemorton]

Closing because this issue is quite old. If this work is still required, please open a new issue.