Added release-drafter.yml

[shikharvashistha]

Reference Issues/PRs #842

What does this implement/fix? Briefly explain your changes.

Greetings of the day @daxpryce,

I would suggest using release_drafter for automating release notes. Please review the pr and let me know in case of any changes/suggestions if required.

Reference : here

Thanks & Regards
@shikharvashistha

[ghost]

All CLA requirements met.

[daxpryce]

I think there's definitely something here to explore more!

• Currently all of our release notes are part of our reference documentation, and I want to continue to include it with our versioned releases within our docs.
• The way it's currently done is we update docs/reference/release.rst
• If there's a way to include the release notes we'd be publishing to Github within our reference documentation, I'm fine with that;
• But if we can also ensure the output of this action also updates the docs/reference/release.rst using the same restructured text formatting we're currently using, that may be easiest (but I'd like for updating our release notes to only be one PR; so a PR for the feature merged to dev, and a PR for the release notes once it goes to dev)
• I do see that the job is supposed to open another PR, which isn't a problem to me, but I wonder if we can use it to update the user's open PR at the time they open it, prior to merging to develop? Then the user (and reviewers) could validate the text looks accurate prior to merging that first PR.
  • This would probably have an issue around race conditions (in other words, if an open PR called dax-open-pr updates the release notes for 0.3.1, but 0.3.1 is released without merging dax-open-pr, the release notes would need to be manually updated in dax-open-pr to put it in release 0.3.2). So... probably better, on balance, not to do it on one fell swoop like I'm suggesting. But maybe there's another way around it I hadn't considered yet :)

Just some early thoughts. Thank you so much for your contribution!

[shikharvashistha]

Greetings of the day @daxpryce,

• What I could infer is you would like to update the release notes as a pull is opened ?

In my humble opinion we can do it in two ways :

1. we can ask the user/contributor to add updated release notes in the pr itself (adding same in pr template and a workflow to check if the release notes have been updated or not) like these guys did here

2. Create a workflow or a python script to run on every opened pr.

• This would probably have an issue around race conditions (in other words, if an open PR called dax-open-pr updates the release notes for 0.3.1, but 0.3.1 is released without merging dax-open-pr, the release notes would need to be manually updated in dax-open-pr to put it in release 0.3.2). So... probably better, on balance, not to do it on one fell swoop like I'm suggesting. But maybe there's another way around it I hadn't considered yet :)

• I guess this won't happen as we're only including the merged pr(in develop) in release notes right ?

• I do see that the job is supposed to open another PR, which isn't a problem to me, but I wonder if ? Then the user (and reviewers) could validate the text looks accurate prior to merging that first PR.

Just some early thoughts. Thank you so much for your contribution!

• I guess that's not the case the workflow will basically fetch the commit messages which are already merged in the develop and will create release notes on that basis. I guess there won't be a need to open a separate pr for that

we can use it to update the user's open PR at the time they open it, prior to merging to develop

• We can ask the user to update the key takeaways of the pr that would be best in this case like I mentioned in the 1. point

What do you suggest ?

Thanks & Regards
@shikharvashistha

[daxpryce]

I was talking to @bdpedigo about this a few weeks ago where I suggested we use the PR title as the release notes bullet, and then be diligent about keeping our PR titles "release notes worthy".

I suggested something like:

• Added Feature[Set] {Title|Short Descriptor} in ModuleOrPackageName
  or
• Fixed bug in [ClassName.method_name|ModuleOrPackageName.function_name] where ShortDescription
  or
• Updated [ClassName[.method_name]|ModuleOrPackageName.function_name] to ShortDescription

If we do that, then we can rely on the PR titles to form the release notes.

I'm still not sure how to make release drafter prepend these changes to the docs/references/release.rst file - like I noted before, there's an output variable that the action provides, so we could theoretically use some bash-cli-fu or python to put that into the right place in the release notes file, but I don't know how to make that work with the version identifier exactly.

On top of that, rst is a pain in the butt 99 times out of 98, so I'm disgruntled just thinking about it. Meh.

Anyway, I don't have any direction yet. Let's treat this as a good conversation spot for now and try to come up with something that works for our release as it is.

There's a possibility we could simplify the release-drafter portion by leaning on releases through Github more vs. our current implicit "prereleases happen when we merge to dev, releases happen when we merge to main" strategy. I just... don't want to rework everything right now, since I'm kinda strapped for time.

Is it okay if we a: keep talking and b: pause if we have to do any major rework of the CICD stuff for it?

(Aside, this is why release engineering is such a pain - it's like an infinite yarn pull of an infinite sweater. It. Never. Stops.)

[shikharvashistha]

I was talking to @bdpedigo about this a few weeks ago where I suggested we use the PR title as the release notes bullet, and then be diligent about keeping our PR titles "release notes worthy".

I suggested something like:

• Added Feature[Set] {Title|Short Descriptor} in ModuleOrPackageName
  or
• Fixed bug in [ClassName.method_name|ModuleOrPackageName.function_name] where ShortDescription
  or
• Updated [ClassName[.method_name]|ModuleOrPackageName.function_name] to ShortDescription

If we do that, then we can rely on the PR titles to form the release notes.

I'm still not sure how to make release drafter prepend these changes to the docs/references/release.rst file - like I noted before, there's an output variable that the action provides, so we could theoretically use some bash-cli-fu or python to put that into the right place in the release notes file, but I don't know how to make that work with the version identifier exactly.

On top of that, rst is a pain in the butt 99 times out of 98, so I'm disgruntled just thinking about it. Meh.

Anyway, I don't have any direction yet. Let's treat this as a good conversation spot for now and try to come up with something that works for our release as it is.

There's a possibility we could simplify the release-drafter portion by leaning on releases through Github more vs. our current implicit "prereleases happen when we merge to dev, releases happen when we merge to main" strategy. I just... don't want to rework everything right now, since I'm kinda strapped for time.

Is it okay if we a: keep talking and b: pause if we have to do any major rework of the CICD stuff for it?

(Aside, this is why release engineering is such a pain - it's like an infinite yarn pull of an infinite sweater. It. Never. Stops.)

Greetings of the day @daxpryce,

I've been researching on automating release notes the conclusion is as follows :

• What are your thoughts on using this.

An implementation of it could be found here.

Thanks & Regards
@shikharvashistha

[daxpryce]

@jonmclean can you take a look into this and see how, if at all, we could get it to work with our new flow now? @shikharvashistha was very helpful and if we can end up using this or modifying it to work with our new doc generation system that would be a very nice thing