Message in Release UI is unclear, possibly misleading

Summary

First of all, I'm not sure whether this is a bug or simply intended behavior with misleading text. Hoping that someone can clarify this before we take any steps to fix it.

On the edit page for a specific release in a project (/<namespace>/<project>/-/releases/v0.1/edit), we display the following text:

Changing a Release tag is only supported via Releases API. More information

The "More information" text links here: https://docs.gitlab.com/ee/api/releases/index.html#update-a-release

The message in the UI seems to indicate that a release can be associated with a different tag (supported by the fact that the "tag name" field is an input). However, the API docs seem to indicate that a tag identifies a release. Since the tag_name parameter is part of the URI, it seems to be immutable for that specific release.

Including a tag_name key in the request payload does not update the tag, so between the UI and the docs, it's unclear what the actual expected behavior is.

Steps to reproduce

  1. Create a project with at least one release and at least two different tags.
  2. Use the "Update a Release" API to modify the existing release and send the following request body:
{
    "name": "Test"
    "description": "Some text here"
    "tag_name": <the other tag that was not used to create the release>
}
  1. View the release again - the name and description are updated, but not the associated tag.

Example Project

I don't have an example project, but not sure the output would be helpful for this particular issue, since it's about the data in the API request body.. Let me know if anyone would like to see the results and I can make one.

What is the current bug behavior?

The tag for a given release cannot be changed.

What is the expected correct behavior?

I'm not sure what the intended behavior is.

The UI indicates that tags can be changed for a release, so if this is true, then the expected behavior would be that the tag_name parameter in a request body would update the release's associated tag.

The docs indicate that the tag_name is used as an identifier for the release, so if that's the case there should not be a message in the UI indicating that the tag name can be changed (or that message should be clearer).

Possible fixes

The release update endpoint is implemented here: https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/releases.rb#L89

Looking at the code, I'm tossed between two possibilities:

  1. The tag cannot be changed for a release because the :tag_name parameter from the URI overrides it in the request body.
  2. The tag cannot be changed because this isn't the intended behavior, in which case we should update the UI to make this more clear.

I'm leaning toward the idea that the tag is meant to be a unique identifier for a release and cannot be changed, but it would be great if anyone can verify whether this is the case.

We had a customer run into this issue recently - they are trying to build a workflow around the assumption that tag names can be changed via the API. More info here (internal link): https://gitlab.zendesk.com/agent/tickets/148251