Problem/Motivation

I love Drupal.org's move to gitlab. I really want to fix code in Gitlab's web IDE. I understand there will always be rough edges because Gitlab is an independent product, with limitd customisation options, and we're pushing the envelope of their expected use cases.

I attempted to use the issue fork and MR workflow in a contrib module to fix an issue, and documented the UX problems I found on the way.

I have briefly read the existing documentation for this on drupal.org, and am familiar with Drupal.org issues and Gitlab issues, MRs and web IDE. But I deliberately did not study the drupal.org documentation carefully.

My UX journey

A. I created #3174319: My test issue in the contrib module xero_sync which I maintain.

B. I pressed the "Fork xero_sync" button.
Problem: that wording does not describe conceptually what I want to do; in the vernacular, to "fork" a project is to create a duplicate of it that diverges permanently as in "Backdrop is a fork of Drupal". I think something like "Start a workspace" or "Create issue branch" might be better."

C. I see "Issue fork" "xero_sync-3174319" "Clone" "You have push access" "New branch".
Problems: (a) Again, I wonder if "Issue branch(es)" would be more to the point than "Issue fork". (b) "You have push access" seems irrelevant, don't all users? (c) The way that the branch name, "clone", and "New branch" are stacked above each other makes their relationship far from clear. Some more spacing above "New branch" would be a quick win here.

D. I click on the branch name and am taken to the Gitlab repo browser.

E. I see the helpful text "For collaboration on https://www.drupal.org/project/xero_sync/issues/3174319". This makes me wonder whether there is more helpful text we could put there. A link to the documentation? An explanation that people can open the Web IDE to make changes?

F. I open the Web IDE

G. I make a change to the readme, and press "Commit".

H. No commit message is suggested for me. I give the message "A test WEB IDE commit #1"

I. I have to choose between "Commit to 8.x-1.x branch" and "Create a new branch" for which there is no default value, but there is a placeholder (which kind of looks like it might be a default value) of "jonathanjfshaw-8.x-1.x-patch-32386". Neither of these options feels comfortable. I don't want to commit my change to my module's 8.x-1.x branch, I want to commit to this issue fork. Intellectually, with some thought, I can figure out why I have these options, but as a user my first reaction is discomfort and nervousness. I would be much happier if the default option was not "Commit to 8.x-1.x branch" but instead "Commit to issue-3174319 branch".

J. There is a checkbox "Start new merge request". It's prechecked, which is good. But I can't imagine any circumstances in which I would not want this, so it's presence seems unhelpful.

K. I'm taken to the "New merge request" page.

L. The title is prefilled with my commit name "A test WEB IDE commit #1". I change that to "A test MR"

M. There are irrelevant fields description, assigneee, milestones, labels, merge request dependencies, approval rules, "Allow commits from members who can merge to target branch".

N. "Delete source branch when MR is accepted" is prechecked and sounds unproblematic.

O. "Squash commits when Merge request is accepted" is not prechecked, and sounds like something I would want. But I leave it unchecked for the purposes of this test.

P. I submit the new MR, and am on the MR page.

Q. I want to go back to the issue to leave a comment, but I can't see an easy way to do that.

R. Back at the issue, I see "jonathanshaw opened merge request !2". Great. I did not make a MR description, but if I had done it would have been nice if it was shown here in the issue comment.

S. Clicking on either of the merge request links takes me to the merge request page. It would be much more helpful if they could take me to the Merge request changes page, so that reviewers would have a 1 click route to be able to review the changes.

T. While viewing the changes, I want to edit the code. That "Edit" button looks very tempting, but that's for editing the MR info not for opening the Web IDE.

U. I go back to the repo home page. I see the branch is set to 8.x-1.x. I think "If I open the web IDE, I'll be editing the 8.x-1.x branch of my module again, not the branch with the last commit I proposed in the MR". I look in the branch dropdown, but don't see other options. Then I remember, "Oh, i didn't create a new branch, I chose to commit to 8.x-1.x, which weirded me out at the time".

V. I open the Web IDE and make another change, and press commit, and give message "A test WEB IDE commit #2".

X. This time the branch selector has "Create a new branch" chosen by default. Which freaks me out, as it wasn't the default last time. Feeling brave, I change it to "Commit to 8.x-1.x branch". The new branch input closes, which I don't remember from last time, so I begin to doubt which option I chose last time and feel scared. I press "Commit" anyway.

Y. Feeling hopeful, I go to look at the merge request. I see that it only has my first commit, not my second. Oh dear. It must be that I created a new branch the first time round even though I thought I didn't.

Z. I understand the problem. I though I was making my second commit in the issue fork, but I wasn't. I was making it in the ACTUAL project repo, not the issue fork repo. Aaaaaaagh. At least this is a problem that will only bite maintainers, but it's not nice at all.

AA. Going back to my test issue, I now have a merge error in my MR because my second commit conflicts with my first.

AB. Going into the issue fork, opening the web IDE, I make my third commit "A test WEB IDE commit #3"

AC. Again, the "new branch" option is the default, not the "8.x-1.x" which I thought was the default last time. That seems odd, but I'll let it slide and choose "Commit to 8.x-1.x". At least this time I'm definitely in the issue fork.

AD. Going back to the issue, I don't see an automatic comment celebrating my new commit. Worse, the issue sidebar is saying some things that are hard to interpret, but it doesn't look like my new commit did go into my MR:

AE. I think what happened is that I did create a branch when I made my first commit, despite thinking I didn't. And so my third commit went into the issue fork, but not the MR branch. Checking the issue fork, that's right, there is a branch jonathanjfshaw-8.x-1.x-patch-32386 which has my first commit on it, while my third commit is on the issue fork's 8.x-1.x

AF. Selecting my branch in the issue fork, opening the web IDE, making a commit "A test WEB IDE commit #4", I see that my branch is the default option, which is good.

AG. But there's a "Start a new merge request" option which is deeply unhelpful. I don't want a new merge request, I want to add to my existing merge request. It's even prechecked! I uncheck it and commit.

AH. Back on the issue, my merge request is no longer reporting an error, as I fixed that in my fourth commit. There's also a comment celebrating my fourth commit.

AI. Gitlab won't let me merge the MR, it's still unhappy about the former merge conflict even though the issue is no longer warning about that.

So that's enough for today ... But from trying this yesterday, I know two more issues

AJ. My commit's in my module won't be using the issue's commit message template, and I'm not sure where I need to use that. Is it the MR title or my first commit on the issue fork branch or my last commit on the issue fork branch? Would be really helpful to have it used by default where it's needed. Or to have these all ignored and just have gitlab's merge use the issue's commit message.

AK. When I merge the MR, the issue fork status is not updated. I'd expected it to be set to "fixed". That's how it works on Gitlab and Github.

Highlights

It's very easy to get confused between the project repository and the issue fork respository, and hard to navigate between them.

It's very easy to get confused about branches on the issue fork repository. Consider making a default issue branch within the issue fork repository.

CommentFileSizeAuthor
#4 screenshot.png15.58 KBdrumm
AE.png39.06 KBjonathanshaw
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jonathanshaw created an issue. See original summary.

jonathanshaw’s picture

clemens.tolboom’s picture

Nice work. Maybe mark the word problem in bold? And make problems nice lists?

drumm’s picture

FileSize
15.58 KB

B. I pressed the "Fork xero_sync" button.
Problem: that wording does not describe conceptually what I want to do; in the vernacular, to "fork" a project is to create a duplicate of it that diverges permanently as in "Backdrop is a fork of Drupal". I think something like "Start a workspace" or "Create issue branch" might be better."

I recently moved the issue forking UI from the sidebar to the main content area, between the files and comments. This gives us a bit more surface area for words and UI elements. As part of that move, the button is currently labeled “Create issue fork.” I do want to keep “fork” as GitHub has popularized forking a repository as the first step in a development workflow. When explaining issue forks, I often mention that they are shared workspaces to collaborate on issues; but I don’t think “workspace” would be a good label, as it isn’t in common use, at least that I’m aware of. “Branch” is not quite accurate, forks can contain any number of branches. We do have an issue for creating the initial branch as part of fork creation #3155690: Add new branch on issue fork creation

(b) "You have push access" seems irrelevant, don't all users?

Once an issue fork is created, other people will see a “Get push access” button. We don’t want people mass-contributing trivial changes to every issue fork, so getting access is a small speed bump.

(c) The way that the branch name, "clone", and "New branch" are stacked above each other makes their relationship far from clear. Some more spacing above "New branch" would be a quick win here.

I think this has improved as part of the recent UI changes:
Screenshot of issue fork UI, after clicking Create issue fork

E. I see the helpful text "For collaboration on https://www.drupal.org/project/xero_sync/issues/3174319". This makes me wonder whether there is more helpful text we could put there. A link to the documentation? An explanation that people can open the Web IDE to make changes?

I opened #3178260: Revise “For collaboration on [issue]” issue fork project desctiption for this.

I. I have to choose between "Commit to 8.x-1.x branch" and "Create a new branch" for which there is no default value, but there is a placeholder (which kind of looks like it might be a default value) of "jonathanjfshaw-8.x-1.x-patch-32386". Neither of these options feels comfortable. I don't want to commit my change to my module's 8.x-1.x branch, I want to commit to this issue fork. Intellectually, with some thought, I can figure out why I have these options, but as a user my first reaction is discomfort and nervousness. I would be much happier if the default option was not "Commit to 8.x-1.x branch" but instead "Commit to issue-3174319 branch".

Agreed, when working in a fork repository, you always want to use branches with different names from the upstream branches. #3155690: Add new branch on issue fork creation should help.

GitLab has some options and permissions that can affect what’s available in its web IDE, but it is mostly not changeable.

M. There are irrelevant fields description, assigneee, milestones, labels, merge request dependencies, approval rules, "Allow commits from members who can merge to target branch".

Agreed. I’ve been looking for ways to control the irrelevant fields. Our options with GitLab are limited, but improving in some cases. For example, https://about.gitlab.com/releases/2020/08/22/gitlab-13-3-released/#squas... now can remove the squash option, but it isn’t yet available in GitLab’s API. We have #3158861: Add open merge request button to issue forks block for potentially creating open-merge-request buttons on the issue page, allowing us to have a much more concise UI.

R. Back at the issue, I see "jonathanshaw opened merge request !2". Great. I did not make a MR description, but if I had done it would have been nice if it was shown here in the issue comment.

Opened #3178262: Show merge request title and/or description in issue page for this.

S. Clicking on either of the merge request links takes me to the merge request page. It would be much more helpful if they could take me to the Merge request changes page, so that reviewers would have a 1 click route to be able to review the changes.

This link was labeled “compare” previously. It is currently “changes,” matching GitLab’s labeling.

AI. Gitlab won't let me merge the MR, it's still unhappy about the former merge conflict even though the issue is no longer warning about that.

Depending on the conflict, this may be improved now. To do a single squash commit, which matches the simple Git commit for a patch, GitLab needs to rebase first. We had the rebasing blocked in many cases, and removed that access check as part of #3072047: Handle merging of merge requests

AJ. My commit's in my module won't be using the issue's commit message template, and I'm not sure where I need to use that. Is it the MR title or my first commit on the issue fork branch or my last commit on the issue fork branch? Would be really helpful to have it used by default where it's needed. Or to have these all ignored and just have gitlab's merge use the issue's commit message.

#3072047: Handle merging of merge requests now adds merging to issue pages on www.drupal.org, which will use the Git commit message at the bottom of the issue page.

When in GitLab’s UI - for merge requests with only one commit, that commit message is used. If there are multiple commits being squashed, only then does GitLab have a UI to set your own commit message, you have to find and click something to show that field. This is part of why we now have our own merge button on the issue page.

AK. When I merge the MR, the issue fork status is not updated. I'd expected it to be set to "fixed". That's how it works on Gitlab and Github.

I opened #3178267: Update issue status on merge request activity? for this, and other issue status updates.

drumm’s picture

Thanks for the thorough review! I think I’ve captured everything in new or existing issues.

It's very easy to get confused between the project repository and the issue fork respository, and hard to navigate between them.

With this, GitLab’s web IDE, and merge requests themselves, our customization options are limited to what the GitLab product lets us do. GitLab has a brisk release cycle, with a new feature release every month. These contain many small improvements like https://about.gitlab.com/releases/2020/09/22/gitlab-13-4-released/#displ....

We should be able to call this issue resolved, and track the various improvements in the issues I called out. If I missed or misunderstood something, you can re-open this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.