(#89) Add ability to populate release notes with information about contributors

[Jericho]

Properly attribute each issue / PR which is part of a release.

Resolves #89

[Jericho]

@gep13 please review at your convenience but do not merge yet. I just rebased your recent changes and I am now investigating how to implement my new feature in GitLat.

UPDATE: I converted to draft to make sure this PR is not merged.

[Jericho]

I solved all the remaining issues. This logic is compatible with multiple issues/PRs being associated with a given issue/PRs and also the GetLinkedIssues method has been implemented for GitLab.

[Jericho]

@gep13 in case I wasn't clear: this PR is ready for review.

[Jericho]

In case anybody is interested to try this new feature, you can replace

#tool nuget:?package=GitReleaseManager&version=0.16.0
with
#tool nuget:https://f.feedz.io/jericho/jericho/nuget/?package=GitReleaseManager&version=0.17.0-collaborators0003

in your cake script and you'll be able to generate release notes similar to this: https://github.com/Jericho/ZoomNet/releases/tag/0.71.0

[gep13]

@Jericho please accept my apologies for the radio silence on this PR! Simply put, I haven't had any time to even think about looking at this. I am hoping to review this in the coming days, and will provide some feedback (if there is any).

Thanks again for your help with this!

[Jericho]

No apologies necessary. I'm just glad to be contributing.

[gep13]

@Jericho apologies again! I haven't had a chance to look at this yet, and looks like I am going to have to do an immediate release to fix the issue with creating releases as a result of a required change upstream to Octokit.

[Jericho]

Rebased to pull in yesterday's commits.

[gep13]

@Jericho is there something "special" that has to be done to get the generated release notes to contain the contributors?

The reason that I ask is that we have an upcoming release of Chocolatey CLI, and I thought I would take this for a spin to see it in action, however, I am not seeing anything other than the normal output in the generated release notes. I can see that in code, the contributors for the issues are populated in the GetContributors call, but the template changes don't seem to be taking effect.

[Jericho]

If you are referencing my beta package #tool nuget:https://f.feedz.io/jericho/jericho/nuget/?package=GitReleaseManager&version=0.17.0-collaborators0003, nothing special that you need to do. The result will be release notes similar to the notes on this project: https://github.com/Jericho/StrongGrid/releases (please note, I started using my beta package in late December 2023 if I remember correctly, so only consider releases since January 2024).

If you are running GRM from source in Visual Studio, make sure you "rebuild" the whole project. It seems that changes to templates are not effective until you rebuild. This issue has caused me grief on several occasions where I modified the template but my changes were no reflected in the resulting release notes. My guess is that this problem is due to Visual Studio not automatically detecting changes to .sbn files. Anyway, long story short: make sure you rebuild the project and you should be good to go.

[gep13]

Thank you for the hint, although that doesn't seem to have helped.

I am trying this out of Visual Studio.

I went as far as closing Visual Studio, manually deleting the bin and obj folders in each project folder, then re-opening the solution, and running the GitReleaseManager.Tool project.

The contributors are still not being added into the generated release notes.

[gep13]

Just tried using the GitReleaseManager.Cli as the startup project, and it is having the same result.

[Jericho]

Please set a break point on line 66 in ReleaseNotesBuilderIntegrationTests.cs and run the SingleMilestone unit test. It will generate the notes for GRM version 0.12.0 which contains a good mix of issues, PRs, excluded labels and, more importantly for the case at hand, 10 different people contributed to this release. When Visual Studio hits your break point, hover your mouse over the result variable and click on View. You should get a popup window where you'll be able to eyeball the generated release notes. I just ran this unit test and here's what I get:

Do you get the same?

[gep13]

No, I do not :-(

Although, I do get contributors back:

[Jericho]

Is there a possibility that, somehow, you managed to override the built-in template with your own?

Also, can you verify that you have the expected index.sbn which should look like this:

[Jericho]

And while we're on the topic of templates, double-check the presence of contributors.sbn and contributor-details.sbn in the src\GitReleaseManager.Core\Templates\default folder.

[gep13]

While I do make use of custom templates on some projects, I can confirm that none are in play when testing this PR. I can confirm this here:

Where the default file path, i.e. the embedded resource, is being used.

Yes, I can confirm that the index.sbn is the same as your screenshot.

And yes, I can also confirm that the two contributor sbn files are in that folder.

[gep13]

Doh! I have figured it out...

I suddenly remembered about the .tt file!

You have to right click on that, and then click Run Custom Tool to have it generate the .cs file, which is then embedded into the assembly.

I don't know exactly when this is run as part of the normal build process, but it might also explain why you found you had to clean the files in order to get things to work properly.

@AdmiringWorm might be able to provide some insight into when this part of the tooling works. Thinking about it, I "think" it runs as part of the Cake build, but I thought it ran inside Visual Studio as well.

Now that I have this working, I should be able to take this for a proper trial.

[AdmiringWorm]

@AdmiringWorm might be able to provide some insight into when this part of the tooling works. Thinking about it, I "think" it runs as part of the Cake build, but I thought it ran inside Visual Studio as well.

It is indeed run as part of the Cake build, it is a separate task called Transform-TextTemplates. Do note that it is not the same as when running it through Visual Studio (not sure why, but the support in VS seems to become worse and worse for TT templates), but it should be close enough.

[gep13]

@Jericho 👋 apologies again for not coming back to you sooner about this one! I would try to give an excuse, but I really don't have one, so, moving on...

A couple of questions/observations...

1. What are your thoughts about adding an IncludeContributors property to the CreateConfig class, to allow control over whether or not to include Contributors within the release notes? As it stands, Contributors are always included, and a user would need to edit the default template if they didn't want to include that information. Having this be controllable via the configuration file would seem like a natural way to do things, and would be inline with other configuration options that already exists.
2. When running the SingleMilestone test (without making any changes to the code) I noticed something interesting. In the rendered markdown, there is this Improvement

Issue 113 was indeed raised by Geoffrey, however, there is a linked Pull Request that was raised by me. Shouldn't the description for this issue include the information about the link to the PR?

3. The default template is becoming quite "busy", with lots of different options and switches that can be pulled. Do you think it would make sense to include another template by default, which would specifically be used when including Contributors? That way, the Default template can remain slightly smaller, and less involved.

4. Instantiating the GraphQLHttpClient here doesn't seem right. This client should probably be injected in the constructor or maybe, rather than mixing the REST GitHub client with the graph QL client in the same provider, there should be a separate provider specifically for graphQL operations.

I haven't really got a strong opinion either way. If we go down the route of using a Configuration value to include/exclude the Contributor information, then we could control when this is instantiated? Or, as you say, perhaps split this out into a separate provider. That might make things a little more complicated in the long run though.

5. I haven't tested this yet against a GitLab repository, as I would need to set one up for testing this out. Things seem a little simpler to do via the GitLab client though, as it doesn't involve GraphQL.

Again.. I am loving this PR, and the functionality that this provides! Thank you so much for putting the work in so far to get this to where it is!