Googletest: Is there a change log available somewhere for the releases?

[SteveBronder]

As title says, I understand writing release notes is a bit of a manual bother but would be nice to have if anyone has time.

[gennadiycivil]

PRs are welcomed of course. We do not maintain an official change log.

[thomthom]

I tried to use GitHub's Compare view, but it wasn't able to display all changes:

https://github.com/google/googletest/compare/v1.8.x...v1.10.x

You get some clues, but many commits just say "Googletest export". Might have to get a git commit history set locally.

We do not maintain an official change log.

Even just broad strokes would be helpful.

[gennadiycivil]

We do not maintain an official change log. However the commit history does have all history with full details for most commits: ( if you click on the "..." for each commit you see the details if you access each commit directly)
For example for this commit
https://github.com/google/googletest/commit/4105eb726341fb79a2f5fbb8bba29e8d1165169b
you see the full explanation

_Googletest export …
Add a compile time check to ensure that the parameters to TEST and TEST_F are not empty
Some compilers may already fail in that case and even where it works, it's likely to result in technically invalid code by virtue of creating reserved identifiers:
https://en.cppreference.com/w/cpp/language/identifiers_

If anyone cares enough to go through the history to generate change log I would be glad to participate. I would suggest to generate a markup file based on the commit history. Send me a PR and we can take it from there.

VERY Broad strokes:

1) This release deprecated "....TEST_CASE" API in favor of "....TEST_SUITE". In a nutshell if you have code that uses something like "INSTANTIATE_TYPED_TEST_CASE_P " - this and all other "*_TEST_CASE " are now deprecated in favor of more standard _TEST_SUITE. See https://github.com/google/googletest/blob/master/googletest/docs/primer.md#beware-of-the-nomenclature.

2) There is new powerful MOCK_METHOD macro. See https://github.com/google/googletest/blob/72adf7a4155b6642da1e6761678fe546590c0269/googlemock/docs/cook_book.md#creating-mock-classes. This replaces older way of mocking.
For example
(Old) MOCK_METHOD1(Bar, double(std::string s));
(New) MOCK_METHOD(double, Bar, (std::string s), (override));
So there is no need to count the parameters anymore.

... may more changes and tweaks.

[roblub]

We do not maintain an official change log.

So why don't you start to maintain it now? It shouldn't be hard. And it does not need to be full changelog; it could be a "NEWS" file that you could update by commits that change a really important things.

However the commit history does have all history with full details for most commits: ( if you click on the "..." for each

I consider this sentence as a non-funny joke. There are hundreds of commits in your repository, and many of them use this "Googletest export" something (BTW. what's the purpose of it?) as their summary, what makes it impossible to select commits that might be interesting. Do you really expect your users to go over all of those changes and manually click "...", just to find out what was changed between releases?

And to be honest I am more interested in a high-level summary of important changes between releases rather than detailed changelog. For example dropping support for pre-c++-11 compilers (if it was really done in 1.10) would be worth mentioning together with those deprecated or new macros you've mentioned.

[gennadiycivil]

@roblub may I gently suggest reading https://github.com/google/googletest/blob/master/CONTRIBUTING.md#please-be-friendly.

dropping support for pre-c++-11 compilers happened a while ago as the documentation suggests.

[gennadiycivil]

I added the 2 high level changes into https://github.com/google/googletest/releases/tag/release-1.10.0. Beyond that and if having a real change log is important for the community I re-iterate the following:

if anyone cares enough to go through the history to generate change log I would be glad to participate. I would suggest to generate a markup file based on the commit history. Send me a PR and we can take it from there.

Thank you everyone.

[SteveBronder]

Thanks @gennadiycivil! I sadly don't have time (any spare time rn is trying to write my own release notes lol)

A thing we've been thinking about doing is in the PR template have a line for release notes so they are easy to pull and construct each release

Feel free to close this issue at your leisure

[roblub]

I added the 2 high level changes into https://github.com/google/googletest/releases/tag/release-1.10.0.

Thanks a lot. Would it be possible to update the link on the main page, under the Announcements section (https://github.com/google/googletest#announcements) as well?

[roblub]

@roblub may I gently suggest reading https://github.com/google/googletest/blob/master/CONTRIBUTING.md#please-be-friendly.

Sorry, I did not mean to be unfriendly. I just wanted to say that you cannot expect users to go through hundreds of commits and click "..." on every of them to learn about new features.
If it is hard to you, as a developer, to summarize the release, then it is even harder to your users.

dropping support for pre-c++-11 compilers happened a while ago as the documentation suggests.

I do not track googletest development regularly. Some time ago I wanted to check what to do with all those "suggest override" warnings, and then I learnt that 1.8 was supposed to be the last pre-c++-11 release. Since that time I've looked on the main page from time to time, quite infrequently. Last Sunday I've noticed that a new release appeared, but the information about c++-11 was no longer under the Announcements on the main page.

Anyway it would be great if you could find some way of managing release notes for future releases.
Maybe it could something similar to the notes that jenkins plugins use, see for example
https://github.com/jenkinsci/warnings-ng-plugin/releases. They seem to use some release-drafter tool for do the job, but I do not know details.

On the other hand it would be also nice, if you could modify your tool, so that it does not add "Googletest export" lines to the commit messages (or adds it to the bottom of the commit message if they are really needed).

Regards,
Robert

[gennadiycivil]

@roblub I updated the link to point to https://github.com/google/googletest/releases/tag/release-1.10.0. (That has the high level available).
Lets talk a bit about the "Googletest Export" Could you please provide more information - what would be useful there?

[SteveBronder]

Lets talk a bit about the "Googletest Export" Could you please provide more information - what would be useful there?

I'm terrible at this but it's supposed to be a headline of what the commit did i.e.

A cool new feature or fixed a bug 

Here's the longer explanation of what actually happened and how the fix is done, side effects, or whatever

It takes a lot of commitment to do that though, squashing/rebasing PRs. imo I think it's pretty easy to have the release notes thing in the PR template and write a python script to grab those. I'm going to do that for my package. If yinz are interested I can send the script your way once I do that

[gix]

Lets talk a bit about the "Googletest Export" Could you please provide more information - what would be useful there?

The whole export process seems broken to me. The first line of a commit message should summarize the commit. I once checked some random offending commits, and they only contained a single change. Dropping that superfluous export-line would have made those commits far more readable.

When I brought this up to another googler, he said he was told it's a limitation, and there can be multiple changes in one "exported" commit. Indeed, checking some of the recent commits some contain multiple changes. Some have one, others have multiple PiperOrigin-RevId numbers (which I assume to be internal changelist ids). Why aren't these split into separate commits?

It really feels as if these Google projects being opensource is just an afterthought, maybe even a nuisance, since they aren't developed here, but internally. Though not every Google project seems to be plagued by this. Just compare tink's commit history with absl's or gtest's.

[gennadiycivil]

@gix thank you for your comments, please see below:

The whole export process seems broken to me. The first line of a commit message should summarize the commit. I once checked some random offending commits, and they only contained a single change. Dropping that superfluous export-line would have made those commits far more readable.

Agreed. We will take a look (no promises on time frame ) if/how we can drop hard-coded "googletest export" message and put the actual meaningful information that is currently hidden below the "..." where you have to click on the "..."

Why aren't these split into separate commits?

Could you please provide a recent example where there is more than one PiperOrigin-RevId number per git commit?

It really feels as if these Google projects being opensource is just an afterthought, maybe even a nuisance, since they aren't developed here, but internally.

May I kindly suggest to read https://github.com/google/googletest/blob/master/CONTRIBUTING.md#please-be-friendly.
The hyperbole such as "afterthought" or "nuisance" have no place in this conversation.

googletest is underpinning about 5 million tests internally and as such the decision had been made to develop it with the source of truth to be internal. At the same time googletest is an important part of the larger C++ ecosystem (see https://www.jetbrains.com/research/devecosystem-2018/cpp/ ).
googletest has a defined process to accept Pull Requests ( and we do accept them ).
googletest has a defined Open Source export process to make the code available to the community. The process is not ideal and can be improved, yes.

The reason this conversation is happening is that there has been a question about the Change Log.
As of today we do not maintain an official change log. We understand that this is not ideal for the community:

1) To retrofit a change log into the current release:
If the change log for the already release code is super important for someone in the community (and as previously mentioned in this conversation) I propose that that person or people in the community would write a script to parse the information already available but not convenient to consume because of the "Googletest Export" . Write a script, create a PR and send it to me for review. I will take the time to look at it.

2) Going forward the only suggestion I have seen so far is to figure out way to not include hardcoded "Googletest Export" message. As mentioned earlier, ack, we will take a look at it.

Thank you

[jzakrzewski]

Is there any progress on dropping that "Googletest Export"? The commit log is basically unreadable because of it.