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
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. |
![Screen_Shot_2019-06-26_at_17.23.46](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
✅ 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. |
![Screen_Shot_2019-06-26_at_17.24.26](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
✅ 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. |
![Screen_Shot_2019-06-16_at_10.19.55](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
✅ 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 |
![Screen_Shot_2019-06-26_at_17.47.50](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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 |
![Screen_Shot_2019-06-16_at_10.31.27](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❓ 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 |
![Screen_Shot_2019-06-16_at_10.33.54](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
💡❗️ 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 . |
![Screen_Shot_2019-06-16_at_10.34.18](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❓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?). |
![Screen_Shot_2019-06-16_at_10.40.49](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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 |
![Screen_Shot_2019-06-16_at_10.44.15](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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 |
![Screen_Shot_2019-06-16_at_10.49.05](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❓ 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. |
![Screen_Shot_2019-06-16_at_10.54.30](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️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 |
![Screen_Shot_2019-06-16_at_10.57.45](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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? |
![Screen_Shot_2019-06-16_at_11.03.49](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❓ 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 |
![Screen_Shot_2019-06-26_at_18.31.51](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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. |
![Screen_Shot_2019-06-26_at_18.35.11](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
✅ I like it that the file is named as <my-project>-<tag-name> . This helps me identify the download easily. |
![Screen_Shot_2019-06-26_at_18.34.09](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
✅ 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? |
![Screen_Shot_2019-06-16_at_11.12.44](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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. |
![Screen_Shot_2019-06-16_at_11.14.14](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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. |
![Screen_Shot_2019-06-16_at_11.14.53](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
Checking my Releases
Emotional grade: Negative
13. Going back to Releases |
![Screen_Shot_2019-06-16_at_11.17.27](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
✅ 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 |
![Screen_Shot_2019-06-16_at_11.23.00](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️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. |
![Screen_Shot_2019-06-16_at_11.24.10](data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==) |
❗️ 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 |
|
|
|