search

joffrey-bion / gradle-github-changelog

Gradle plugin that generates a changelog from Github issues and pull-requests
MIT License
8 stars 1 forks source link

Release header mismatch #30

Open matshou opened 3 years ago

matshou commented 3 years ago

Release headers are not properly matched with release text content.

I've provided two changelogs in an attachment below to demonstrate this issue:

As you can see every header has been moved up for one slot, also notice how v1.0.0 does not have a link to full changelog.

Attachment: mismatched-changelogs.zip

joffrey-bion commented 3 years ago

Thanks for opening this.

Did you use any particular config, or are you using the default?

I always use futureVersionTag myself, so maybe there is indeed a bug when using the "unreleased" default.

matshou commented 3 years ago

This is my plugin configuration:

changelog {
    githubUser = 'yooksi'
    githubToken = "${superSecretToken}"
    githubRepository = rootProject.name
    outputFile = file("${projectDir}/CHANGELOG2.md")
}

I will try running with futureVersionTag and report back.

joffrey-bion commented 3 years ago

Thanks! I tried on a couple of my repos without futureVersionTag, and I can't reproduce this issue.

I opened this for the full changelog on the first tag: https://github.com/joffrey-bion/gradle-github-changelog/issues/31

matshou commented 3 years ago

I've tried running with futureVersionTag alone as well as in combination with showUnreleased and the issue persists.

joffrey-bion commented 3 years ago

@yooksi I took a look at your repo.

The issues and tags dates are correct: the issues were closed after the tag, that's why they appear in the next section. This changelog generator works by date: the issues for one release are the issues that were closed between the previous tag and the release's tag.

On which basis does github-changelog-generator put your issues in 2.0.0 or 2.1.0 of your changelog?

matshou commented 3 years ago

The issues and tags dates are correct: the issues were closed after the tag, that's why they appear in the next section.

I am not sure if that is correct, take a look at commit https://github.com/yooksi/pz-zdoc/commit/3bed3679efa9f6b6155f857ec7322d4c478a6b3e, it was commited on 2021-01-31 17:47:20 +0100 while tag v2.0.0 was created on 2021-01-31 17:53:11 +0100.

It was closed before v2.0.0 but is listed under v2.1.0.

joffrey-bion commented 3 years ago

Mmh maybe I just got unlucky then, lemme take another look.

EDIT: interesting the commit was done at 17:47 (GMT+1), yes, but the issue was closed only at 18:11 (GMT+1). And the tag is indeed 17:53 (GMT+1).

joffrey-bion commented 3 years ago

It's based on issue closing time, not on the commit time. I guess the commit was pushed or merged later in this case?

Maybe the bug lies here. If the commits are made locally as well as the tag, and everything is pushed later, then the issues will be closed after the tag date.

matshou commented 3 years ago

That particular issue that I linked was (like most others) closed with a release merge commit that was tagged soon after.

Maybe the bug lies here. If the commits are made locally as well as the tag, and everything is pushed later, then the issues will be closed after the tag date.

Isn't that part of normal workflow though? You prepare everything locally and then push it to origin, which will always result in issues being closed after commit and tag dates. How does your release workflow look like?

joffrey-bion commented 3 years ago

Personally, I push or merge commits regularly to master, closing issues with the commits. When the time comes to release, I generate, commit and push the changelog, and tag this commit with the version (hence the use of futureVersionTag, but this is irrelevant for past releases).

So basically I always pushed everything before tagging for some reason. Now it's even more certain because I use GitHub Actions workflows to do all that for me at the click of a button (see this for instance: https://github.com/joffrey-bion/gradle-github-changelog/blob/main/.github/workflows/release.yml)

Anyway, your workflow should not be to blame, although technically you do close issues later than your tag. I wonder if there is a way for me to get the information about the closing commit from github.

matshou commented 3 years ago

I wonder if there is a way for me to get the information about the closing commit from github.

It would probably be best to see how github-changelog-generator handles this.

In the meanwhile I will get to work by editing my past tag dates 🏷️⌚

joffrey-bion commented 3 years ago

See this: https://github.com/github-changelog-generator/github-changelog-generator#features-and-advantages-of-this-project

Manually specify the version that fixed an issue (for cases when the issue's Closed date doesn't match) by giving the issue's milestone the same name as the tag of version

But you didn't use milestones for 2.0.0, right?

It could also be due to poor granularity (if github-changelog-generator only looks at dates, not date+time).

joffrey-bion commented 3 years ago

In the meanwhile I will get to work by editing my past tag dates

I could also implement a feature similar to the one I linked above. This would allow to override the behaviour in bulk.

matshou commented 3 years ago

But you didn't use milestones for 2.0.0, right?

I have a milestone that contains issues closed by v2.0.0 but I did not specify it before generating.

It could also be due to poor granularity (if github-changelog-generator only looks at dates, not date+time).

This is probably the most likely explanation.

I could also implement a feature similar to the one I linked above. This would allow to override the behaviour in bulk.

That would definitively solve this issue.

I would suggest you include a note in the plugin README that explains this problem and instructions on how to avoid, namely to make sure they create and push their release tag after they pushed the release itself to remote repo.

matshou commented 3 years ago

I have updated the date of all tags in pz-zdoc repository so that they are dated after the closure date of all commits belonging to their respective releases. However, the plugin is still not generating a correct changelog.

Here are the updated tag dates:

v1.0.0 Sat Dec 5 23:42:20 2020 +0100
v1.0.1 Sun Dec 6 01:24:17 2020 +0100
v1.0.2 Sun Dec 6 11:13:00 2020 +0100
v2.0.0 Sun Jan 31 18:12:00 2021 +0100
v2.1.0 Fri Feb 5 20:01:00 2021 +0100

Examples of misplaced commits:

joffrey-bion commented 3 years ago

Thanks a lot for reporting back, I will look at it ASAP:

Links:

matshou commented 3 years ago

Just stumbled upon this while reading the github-changelog-generator help:

--[no-]filter-by-milestone   
Use milestone to detect when issue was resolved. Default is true.

Could be an alternative way to determine when issues were resolved.

joffrey-bion commented 3 years ago

Yes, this is what I was talking about in my comment above.

I think I'm going to add this feature.

joffrey-bion commented 3 years ago

Milestone override support was done in https://github.com/joffrey-bion/gradle-github-changelog/issues/33.