Empty release notes should fall back to Git tag message

[fumoboy007]

Please describe the bug

I’m looking at the release notes generated by Swift Package Index for the fumoboy007/msgpack-swift package. It says “This release has no notes.”

The GitHub release notes have a different behavior: they fall back to the Git tag’s message.

Explain the steps needed to reproduce the bug

1. Navigate to https://swiftpackageindex.com/fumoboy007/msgpack-swift#releases.

What was the expected behaviour?

The release notes should show

1.0.0: Initial release.

• MessagePackEncoder to serialize a Codable value to MessagePack bytes.
• MessagePackDecoder to deserialize a Codable value from MessagePack bytes.
• MessagePackTimestamp to represent MessagePack timestamp values.
• CodableAsMessagePackExtension to implement application-specific MessagePack extension types.

Screenshots

[Sherlouk]

Worth noting the implementation of this was done in #1224 - but was decided against as it was felt unnecessary.

Will leave to Dave/Sven to comment though!

[daveverwer]

Thanks so much for the issue, @fumoboy007. I’m sorry it doesn’t behave as you expected.

With #1224, I had some concerns about the feature, but I certainly didn’t feel it was unnecessary. It also looks from the screenshots in that thread that GitHub was hiding commit messages behind a click at the time.

While I would certainly like us to do a better job with release notes for packages that don’t have explicitly written ones, we’re not trying to copy GitHub functionality identically.

Since the current behaviour is not a bug, I’ll transfer this issue to the Discussions area, not to demote it but to move it to where we discuss all community feature requests. If it gets more support/discussion and/or someone who would be interested in working on the broad problem of “better release notes in the absence of explicitly written ones”, we’ll get it straight back to being an issue for implementation.

To be clear, I would support work to improve our release notes feature, even if that does end up being “just” echoing GitHub’s implementation. However, a feature like this needs approaching with a bit of thought, even if it’s just about dealing with edge cases (a release with 10,000 commits or extremely long commit messages.

[fumoboy007]

Thanks for the thoughts, @daveverwer!

Swift Package Index is using GitHub’s releases feature though. So why shouldn’t it be a requirement to match GitHub’s behavior here since it’s their feature and they intended an empty release note to fall back to the tag message?

Relatedly, why are we even using GitHub’s releases feature instead of just relying on the tag given that the tag is what Swift package manager looks at?

[daveverwer]

Swift Package Index is using GitHub’s releases feature though. So why shouldn’t it be a requirement to match GitHub’s behavior

I mean we're getting into semantics here, but again I'd phrase it differently. GitHub don't make their release "feature" available as a "thing". We could build our own implementation of it using the data they make available via their API, but there's no way at all for us to match their feature exactly. If we chose to mirror their design 1:1, which is not even our intention, we'd need to build every piece of it separately.

why are we even using GitHub’s releases feature instead of just relying on the tag

That's exactly what we do. Our "release feature" works entirely off tags, and for exactly the reason you say. Because that's how Swift Package Manager works.

We did that first and got it all working and made each release link to the GitHub release page. Then, many months later decided that it might be good to try and bring that metadata into the SPI site itself, so the system now checks whether GitHub also has release metadata available for the same tag we are tracking. That's where the information you see today in the releases tab comes from.

We could, in this case many years later, decide to enhance our feature further by also including commit messages if we are not able to find any release metadata, which is what we are talking about in this thread.

[fumoboy007]

including commit messages if we are not able to find any release metadata, which is what we are talking about in this thread.

Ah, I think I see where our miscommunication is coming from. My proposal is different from #1224, which is falling back to the commit message. I was proposing that we fall back to the tag message that is entered via git tag -a 1.0.0 -m "My tag message".

Further confusing things is the distinction between Git tags and GitHub releases. These are two separate concepts. A repository could have a Git tag without a corresponding GitHub release.

There are three levels of abstraction here:

1. Git commit.
2. Git tag, which points to a Git commit and can have its own message.
3. GitHub release, which encapsulates a Git tag and can have its own description.

Our "release feature" works entirely off tags

This is not true. Swift Package Index queries GitHub releases, not Git tags. If I created a Git tag but did not create a corresponding GitHub release, Swift Package Index would not show it.

---

Ideally, I think we should query all Git tags instead of GitHub releases (and filter out the ones that the Swift package manager does not support). We could also query the corresponding GitHub releases if they exist and merge the two. But the Git tags should be the main thing we care about, not the GitHub releases.

Here is an example query to get the Git tags of a repository:

{
  repository(name: "msgpack-swift", owner: "fumoboy007") {
    refs(refPrefix: "refs/tags/", first: 20, orderBy: {field: TAG_COMMIT_DATE, direction: DESC}) {
      nodes {
        target {
          ... on Tag {
            id,
            name,
            message
          }
        }
      }
    }
  }
}