Release UX Scorecard: Create a Release and update it

JTBD: Create a Release and update it

When tracking important deliverables in my project, I want to easily create and manage release entries in GitLab, so I can provide a packaged software, notes, and files for people to use.

Checklist

• Document the current experience of the JTBD, as if you are the user. Capture the screens and jot down observations. Also, apply the following Emotional Grading Scale to document how a user likely feels at each step of the workflow. Add this documentation to the epic's description.
• Use the Grading Rubric to provide an overall measurement that becomes the Benchmark Score for the experience, and add it to the epic's description.
• Once you’re clear about the user’s path, create a click through video that walks through the experience and includes narration of the Emotional Grading Scale and Benchmark Score.
• Post your video to the GitLab Unfiltered YouTube channel, and link to it from the epic's description.
• If your JTBD spans more than one stage group, that’s great! Review your JTBD with a designer from that stage group for accuracy.
• Create an issue to revisit the same JTBD the following quarter to see if we have made improvements. We will use the grades to monitor progress toward improving the overall quality of our user experience.

Current experience of the JTBD

🚀 Overall Experience: F (Poor)

📹 Experience baseline video: See it on GitLab Unfiltered

Creating a project

Grade: Positive

I want to start exploring the Release feature for a new project. I am a GitLab user and am logged into my account. I create a new project under a personal group project at GitLab https://gitlab.com/rayanaverissimo/jtbd. Creating a project was pretty straightforward:

1. From the homepage I click on the New project button.
✅ I can easily identify the button by its color. It seems it's the only call to action on the page

2. I click on the button and am taken to a page where I can fill in the details of my new project.
✅ I can easily fill in the details for my new project
❗️ I find the page a little bit cluttered, there is a lot of text being showed, but nothing that stops me from understanding how to do my task

3. After choosing a name entering a description, and selecting the settings for my project, I hit the Create project button. I am then taken to the detail view of my newly created project.
✅ Nice! Creating a new project was fast and easy! I can now start working with my project and creating Releases.

Figuring out how to work with Releases

Grade: Negative

4. I search for help on Google
❗️ I google for releases page gitlab and end up with two different search results for what is the documentation for Releases -- one for the workflow, and the other one for user documentation.
❓ This is a bit confusing to me, as I am not sure which docs to follow and I'll have to read both pages to understand which one is going to help me set up Releases.
❓https://docs.gitlab.com/ee/workflow/releases.html: This doc seems a bit incomplete and only provides two screenshots of where to click on a page to create a release. The UI of the screenshots presented are also different from what I see on my GitLab instance. I don't understand why this is still in use.
❓https://docs.gitlab.com/ee/user/project/releases/ This doc is a bit more complete, with updated screenshots, and talks about release assets and lists.
💡 I realise there are three different ways to create a release with GitLab: 1. In the interface, when you create a new git tag 2. In the interface, by adding a note to an existing git tag 3. Using the GitLab API. For this exploration, I will try to create a release using the interface only.

5. Reading the Release documentation
❓ The release doc is not specific on where I should go to create a release. It simply starts saying that I can Start by giving a description to the Release and including its assets. But where do I have to go?
💡 I will check back on my project

6. Browsing my project for the Releases functionality
💡❗️ Going back to my project, I start browsing the side menu for an indication of where the Releases feature is located. Ha! How did I miss this?
✅ I quickly spot the Releases menu option under the Project section of the menu. I click on it.
❓ I am taken to what seems to be a main page for Releases. But I don't have any Releases created yet. The empty state message says Currently, releases can only be created through the API. This is confusing to me, as previously reading the docs it stated that There are several ways to add release note. What is the difference between adding release notes vs. creating a release? Also, the other doc page says At the moment, you can create Release entries via the Releases API; we recommend doing this as one of the last steps in your CI/CD release pipeline.
❓I am prompted to the documentation -- which is a different page from before but with the same content (why do I see 3 different documentation pages for the same feature?).
❗️ I feel frustrated that I can't create a release from the Releases page and decide to try the second workflow: create a new git tag.

Trying to create a new git tag

Emotional grade: Negative

7. Exploring the Tags functionality
❗️ Once again, the documentation pages are not clear on how/where to create a new git tag. I decide to explore the side menu to find where Tags live. I find the Tags option under the Repository menu option.
❓ The Tag name sounds a bit confusing. It can be understood as a project tag, a git tag, an issue tag...
❗️ Clicking the menu takes me to an empty view of the Tags page. I find it weird that the empty state message style is different from the one I just saw for Releases.
✅ The copy in the UI tells me that my repository doesn't have tags yet, and that I can use git tag command to add a new one. I want to create tags using the interface, so I look for a button that reads 'create', or 'new'. On the top-right of the screen I see a button that reads New tag. I hope I will be able to create a release tag from there.

8. Creating a and managing a git tag
❓ The page opens to a form for New Tag. I scroll down and see I can add release notes to a tag.
❗️ I fill in the information for the new tag. There's no indication of what's the best way to name my tag, so I name it test-tag.
❓ The Release notes text field is confusing to me. A helper text is displayed and reads Optionally, add release notes to the tag. They will be stored in the GitLab database and displayed on the tags page. Does this mean my tag will create a new release? There is also no reference to any documentation or more information I can follow... so I simply add some dummy text and attach a test file to see what happens.
❗️I click the button Create tag. This action feels unnatural to me, as I want to create a release and not a tag.

9. Viewing a git tag
❗️ After click the button to create a new tag, I am redirected to the detail view of my new tag. The page layout is very unpleasant to look at, with my uploaded asset displayed full-size and my tag description placed in a weird position on the top-right of the screen.

10. Editing a tag?
❓ I am now given the option to Edit release notes, Browse files, Browse commits, Download, and Delete tag.
❓ At this point I don't see any reference to a release per se. Is my tag name my release name?
💡 I decide to navigate using the breadcrumbs menu to go back to the Tags overview page.

Download release assets from the Tags view

Emotional grade: Neutral

11. Downloading assets
❗️ There I see the same information from the Tag detail page. The page layout again seems weird to me, as the assets I uploaded take the full height of the notes area, pushing the Download, Edit release notes, and Delete tag down.
✅ I click the Download dropdown button to see what happens. I am given the option to download assets in different formats. I click the zip format and a file is downloaded to my computer.
✅ I like it that the file is named as <my-project>-<tag-name>. This helps me identify the download easily.
✅ I unzip the file and inside I see the current files in my repository (currently only a README.md). Nice! It works!

Creating a tag without release notes

Emotional grade: Negative

I decide to create a new tag, but this time I won't include any release notes.

12. Creating a new git tag without release notes
✅ On the top-right of the screen I see a button that reads New tag. Clicking the button opens a form for New Tag. I fill in the form but skip the release notes field. What will happen?
❗️ I click Create tag and am redirected to the tag detail page. There is a text in the page that reads This tag has no release notes. Once again, the page layout seems funky to me and I am not pleased to stay navigating on this page. I click the breadcrumbs menu to go back to the Tags page.
❗️ I now see both my tags displayed. It is interesting that my old tag is displayed on top of the new one. Both share the same latest commit, but I expected to see my new tag on top of the old one. I see no reference to Releases on this view. The page layout is not the best. I decide to explore Releases again.

Checking my Releases

Emotional grade: Negative

13. Going back to Releases
✅ I navigate to the Releases page using the side menu. Now it seems I have a release to available.
❗️ Wow! The first thing I notice is that the page layout cannot contain the image I uploaded to the description of the release note.
❗️I am not given the same action items I had in the tags page: the delete, edit, download etc, buttons are not present. Instead, I see text with information about the commit, tag, release date (none of those are clickable), and number of assets with a dropdown option.
❗️It is confusing that the UI and action items are different here. I expect more homogeneity.
❗️Still, I cannot create a release from this page, nor edit or delete it.
❗️There is also no option to see individual release details from this page, only an overview with a list of all releases.
❗️The workflow seems incomplete to me, but I have managed to create a tag/release.

Checking where else I can see my releases

Emotional grade: Negative

14. Trying to find my releases in the project overview page
❗️Because I am familiar with the Release workflow from GitHub, I decide to try to find mentions of my release/tag in my GitLab project. I go to the repository main page and look for a link to my release... I don't see anything.
❗️I notice later that there is an option that display my project tags.
❗️ I am a bit frustrated that I cannot jump to the releases from the project main view.
❗️ I feel this whole time I was playing with Tags instead of working with Releases. I would like to have everything in one single place

Recap

Overall Experience	❌ F (Poor)
Creating a project	😃 Positive
Figuring out how to work with Releases	🙁 Negative
Trying to create and manage a new git tag	🙁 Negative
Download release assets from the Tags view	😐 Neutral
Creating a new git tag without release notes	🙁 Negative
Checking my Releases	🙁 Negative
Checking where else I can see my releases	🙁 Negative

What didn't go well

Workflow	Interaction Design	Layout	Feedback and communication design
1. Unclear path to create and manage a Release	1. Navigation is not optimal	1. Page layout is broken for tags and releases	1. Unclear labeling of Tags and Releases makes it difficult to distinct functionalities
2. Unclear/incomplete documentation about Releases	2. Option to download assets is displayed different in detail and list views	2. Tag and Release detail view does not support full screen images	2. Project overview only display tags, not Releases
3. Finding Releases is not easy	3. Creating a Release from the Tag form is confusing
4. It is not possible to create releases from the Releases page
5. Tags and Releases live in different menu options