GitLab UX Team, 10 Jul 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: How to Make UI Text Changes in GitLab (Designer Edition)

Description

A tutorial on how to change UI text strings in the GitLab codebase. Though especially for semi-technical/non-developer contributors like UXrs and Product Managers.

Tutorial pre-requisites and covered examples:
https://docs.google.com/document/d/1peJbV3kN10N4m59v8XDNJQ0QC0VLn6jMTRTfhpBL3SM/edit?usp=sharing (Only accessible with @gitlab.com addresses.)

A

Hello, my name is Juan Ramirez product designer for the runner and testing teams lead lap, and this video that I'm doing today is a video that has been asked by many people, which I think it's gonna be very helpful and these videos gonna be about how to make UI text changes to get lap, and today, I'm, just gonna do like a brief tutorial on how to do that.

A

I'm gonna try to be fast, but also I'm gonna try to have a good pace, so whoever is watching this video can follow along and we are just gonna do two examples today. Hopefully those two examples can address some of the use cases that are for this, for this particular type of changes and there's, of course, gonna be more things that probably are now gonna be covered in the scope of this video.

A

But anytime, you can just send me a slack message or you can just ask for me to expand more and I'll probably can do another of these videos with more details. Okay, so with that being said, what I'm gonna do right now is I'm gonna share. My screen and I'm gonna show some introductory stuff that it's going to help us to move along with this tutorial right through my screen. Right now,.

A

Also, during the course of this video, my main screen is gonna, be in front of me. My camera is gonna, be here so I'm lightly gonna be looking at this screen.

A

So it's going to look a little bit weird, but this is just just bear with me: alright, so so how to make UI text changes in grid lab. So that's something that it's a small change. It's a small thing that people want to do, and it's usually not that hard, but it has some some complexities and I'm gonna. Try to help you today to navigate and browse those those complexities. So you can like anyone who's watching this video and it's not a developer. Not it's!

A

Not a front-end or back-end developer can still make this changes, because we have a lot of these things that are like really low hanging. Fruit, like one example of those things is changing text that it's entitled case it should be in sentence case. You know we we have some of those inconsistencies across the the UI and that's something that it's a very small contribution.

A

That can add a lot in terms of consistency and how professional our website looks like and there's, of course, many other things just from fixing typos to making language more clear, there's a lot of stuff that that can help a lot to make it love a better tool and because we're very verbose in terms of what we present in our UI is it's very important to have those texts right and that's why I wanted to make this tutorial. So anyone who is not 100% technical can still do this type of changes.

A

So all right so I want serve with the prerequisites. There's three, the first one is you want to have GTA v, DK installed and configured. If you haven't done that, there's a set-up guide that you can use like just follow along and you should be able to set up a working GD k after you do all that stuff.

A

The other thing is that, as part of cloning, you you need to clone. As far like setting up your GDK, you need to clone and get the project into your GDK.

A

When you do these, you wanna make sure that you clone that via SSH, and then you set up public key and public SSH key in your get lab and the reason why is because that's the easiest way to make pushes, if you do it through HTTPS, which is the other alternative, it becomes way more tricky. Sometimes the terminal is gonna. Ask you for the credentials every time that you're gonna do a change. It's not a smooth so make sure that you do that. I. Also added a link here. I'm gonna, be sharing.

A

This document and I'm gonna add that in the description of the video, so you just make sure that you have this set up this way and finally, you need to have a code editor. Any code editor will make it, but my suggestion is use Visual, Studio code, that's the canonical editor in the industry and it works pretty well and that's the one I'm gonna be using in these tutorials, so yeah just make sure to set that up as well. Okay.

A

So what are we gonna be learning today we're gonna be learning how to identify the text that needs to be changed in the local installation, so basically just going in your local installation and trying to find that text that you want to change. Find means that takes in the files using Visual Studio code determining what files need to be changed once you're in Visual Studio code, and we identify those files your you're gonna need to determine.

A

Why do you want to change and that's a little bit of a tricky part of doing these, but I'll give you some some tips on that and pushing the change and opening and Ammar with the changes and I'm gonna show you that you can open anymore and you're, not gonna affect absolutely anything. Nothing is gonna change. The main code base, not nothing's, gonna, make it to master. Unless someone approves that and makes it to master that way, you know so you can push whatever you're gonna open any kind of Tamar.

A

It's not gonna. It's not gonna break anything so I'm. Also wanting to do the confidence that doing this is not gonna break anything that you can test. You can basically experiment as much as you want and I. Also I'm gonna cover some caveats and some some tricky stuff on these mainly translations, which you have to run every time. You push changes, text, changes and tests, because sometimes many of these things are being tested in entertain, like jobs that are meant to test the code.

A

And if you change the test, the text, then it might break an actual test from from the ones that we really need lab. So so I'll talk a little bit about that as well. All right, so I'm going to do two two examples. The first one is in CI CD settings, there's heading that's protected environments, title case and we're going to change that to protected environments sentence case and then in CI CD settings. There's a button that says add variable at a location, we're gonna change that sentence case and just see be super up.

A

A prawn heads up I just saw those examples. I didn't test these before, so any hiccups that I find throughout these are gonna, be the same hiccups. Oh you're gonna find when doing these. You know and I'll try to figure out those things and I um I didn't prepare anything beyond this document, so you can also kind of like find your own workflow and I'll. Show you how what my workflow is. Sometimes my workflow implies going and googling stuff, like the translation job that you gotta run in your terminal.

A

Once you make the translations I, don't know that off the top of my mind, so I always google that, and you will see me doing that so all right. So enough talking, let's jump into the action all right, so I'm gonna, open, peaceful studio. First I already have a block open here. So what you want to do is you want to go? You want to open the folder in which your gitlab leaves right.

A

So in this case you just want to go to having my desktop and GDK here and I have to GD case I have what I'm working on GD k, 2 and then I'll find a get lab. Folder here, which is this one, and then you want to open that one right now, I already have it open, so I'm not gonna open it again, but you get idea, okay, so the other thing is just basically finding those examples that I talked about before right.

A

So all right, so I said that those two things that I want to change: they are. They live in settings so right now you're seeing my local installation. This is my DD k, as you can see here.

A

Let me just move this to the top one minute, all right, just gonna notate some things as I talk. Alright. So, as you can see here, I am my local host right, I'm, not working out of the cloud or anything. This is my local machine with my local installation of get lab. This is get lebron freaky-deaky.

A

Alright, so let's basically go to any test. I'm gonna go to this test. Sorry I'm to any project. I'm gonna go to this project and then I was talking about text mixing settings. It's particularly CICE settings, so I'm just gonna go to the CI CD settings and I want to change this protected environment. So now the question is how how how am I going to find these texts in the files- and the good news here is that most of the times is gonna be very straightforward.

A

You know it's gonna, be a matter of just finding these exact text in the UI. Sometimes you're gonna get more tricky because sometimes we have so so much repetition of concepts. You're gonna find multiple instance of the same type of text around you know and through those cases you might wanna. You know star like looking for more longer strings and then like trying to find that like if that string is the in the same file. So one example is if this was a very generic piece of text.

A

You might want to try to find this one first, protecting an environment, blah blah, find that your your visual studios, I'm gonna, explain in a minute and then within that file. It's likely that this particular one it's close to these, because it's basically the same component or the same template or whatever. So that's just like a small strategy for the examples that I pick I'm, think I'm gonna find them right away.

A

I don't know yet this one seems to be very straightforward, so I'm, just gonna like copy this text, cities and then I'm gonna, go to visual studio and, like is bigger. Okay, so now I'm in Visual Studio.

A

The most important thing for this workload, I'm explaining here is this search guy, so search in Visual Studio is very, very powerful when I'm talking about search I'm, talking about I'm talking about this guy this guy here, this one is pretty pretty good for what we're gonna do and it's what makes before story very powerful I haven't tried other search functionality. You know there are editors, but I know this. One is pretty good. So just have that in mind all right.

A

So you go to search, and then you are gonna find these two things here: search replace you don't want to do the report like the search and replace that. Never do that because, like you, you're gonna break things. What you want to do is search the text, and then you want to change that on the text. Editor itself just make sure that you're changing the right things. A couple of things like the first one is this little thing here.

A

This means that way when you toggle this on, it's gonna find text respecting the text case right. So, if I type something in caps, it's gonna find only text that it's in caps right- and this is good when you're trying to find like train stance this this thing that we're trying to find right now. You can always turn out these. If I, if I do protected environments, you're gonna see that it finds a lot of files in which the environments piece of the string is not it's not capitalize.

A

The first letter, that's right, but we have this toggle, but it's gonna make our life a little bit easier. Then I'm just gonna turn it on, and now it's gonna find only those instances where we have protected environments using the the first letter in environments capitalized. Alright, so you are gonna, get a lot of files, change locks, anything that exchange locks or anything that it's a markdown file ignore those.

A

That's not what you want to change, then the most likely thing that you want to change is either a handle file, a ruby file or a dot view file. Those are the three type of files that you are likely: gonna change when you're changing text.

A

You also want to look for one particular thing like strengths in gitlab are usually international or translated, because we have, we can all eat, love, it's also presented in other languages. So we have this service that translates all the strings. So when people use, let's say, kidnapping Japanese, they see the actual strings in Japanese, which brings me to an important point. You're gonna see a lot of translation files like this one. You can totally ignore these, never change those those are generated automatically, so you don't have to change those.

A

So again, what you want to make sure is that you're, finding strings in Ruby files in Hamel files, or in that view, files coming back to what I was saying before those internationalized strings are usually encapsulated in a markup that looks a little bit like these I'm gonna put it in replace, but it's not because I'm gonna replace it it's because it's the only text that I have area of text that I have to type something right now, but it looks a little bit like this.

A

It looks like like this little bit so you're gonna have a piece of text here and that it usually looks like that. That's when you find text that it uses that pattern like where the string is encapsulated in that type of markdown, it slightly text that that's like the text that you want to change. So if you look in the files that we found, there's one that actually is doing that and meets all the conditions that we just talked about. It's not harm out file, and it has that type of markdown that I just explained.

A

So what I'm gonna do is I'm, just gonna click here and it's going to open the file. This file put it on Ruby, that's very likely the file that we want to change right. It has many of the Telltale's that it's the thing that we want to change friends and it's one of those Telltale's is that it's talking about expand button right and when you go when you go here, there's expand button here right, like so like it is likely a template that is being rendered from the server it's.

A

What it's being put here and yeah, it's I'm, almost 100% sure that this is the the text that we want to change. So to do that very simple: we're gonna change it now and then we're gonna verify if we actually need the change. So I'm just gonna delete that now it's sentence case: I'm gonna, save it um I'm gonna go back to my GDK running DDK, my local d-block and I'm, going to refresh.

A

And as you see it change, so we are good. We just changed that it's. We already did a meaningful change, intent in terms of consistency and in that and that can I take you a long way. It can help you to do a lot of other things, and it was very easy. So we just need that change.

A

So that's right, so fortunately that was an easy one. Sometimes they are not as easy and that's why I pick a second example, and that second example is a bottom. This add variable bottom I know because I have seen I have work with the gitlab code base before that buttons are not coming from templates Hamel templates, they are coming from likely components, view files. So that's why I pick this one but I don't know what's gonna happen, so we're gonna find it again and we're gonna try to change it.

A

So we already know a couple rules. So just as a reminder, those rules are Hamel files, sometimes Ruby files, things that any dot RB and I'm gonna explain that the tests at the end I haven't gone into that yet and then the other file is dot view file, so, okay, so add variable still when I use this toggle on, because I want to find that a specific instance of that text.

A

There you go that one was pretty easy as well, because the first file that we're finding meets that condition of the markdown that I explained at the beginning. It's it has this underscore and then it has the parentheses and then it has the text. So it's likely that this is the text that we are looking for, so I'm gonna open and it's that blue file. So it meets that condition.

A

I'm gonna explain it the test, the changing the test. I, don't know if these house tests, but I, don't think it does, but I'm pretty sure that if I believe this I'm gonna find some tests for this particular file.

A

Yeah there you go so you're gonna find some files like this one that an inspector Jes or expect dot RB RB and those files. You don't always need to change those files, but you gotta make sure that those files are not testing for text conditions and what that means is that sometimes these files, they are very easy to read.

A

Actually so like, don't be stir about why you're really here, but sometimes these files will have like tests that read something like describe something adding a new variable and maybe there's gonna, be something that says, make sure that that button is present and then what it's trying to test for is the presence of the test, all the text that sounds kind of weird. But when you find those you, you will know what I'm talking about like I. Don't know. If there's one in this example that I can use. Actually, there's one see this.

A

One is a good example what this, what this particular test is looking for. Is this thing that says update variable? So if you change whatever text, this is testing.

A

Let's say you are changing this to title case so somewhere in that view file. You change this world to change something to update the update variable we with this one capitalized. If you don't change that that test here to that, then what happens is when you run the pipeline. It's gonna fail because, like the pipeline is gonna, be like oh I, like I, didn't find that that the text you know I'm still looking for one that it's in sentence case not in title case so I know.

A

That's kind of weird I know that I'm, like basically jamming this in between, but I just wanted to mention that, because you're gonna find some instances of that and I want to make sure that you you're aware of those if you're having trouble with those feel free to ya just message me or you can talk with one of your front-end engineers they they will definitely know how to fix that. But yeah just be aware of that. Hopefully, you're not gonna find a lot of those, but it happens.

A

Sometimes it has happened to me in the past. So anyways we were here. We were gonna change. These these little do to add variable. First I wanna show you that there's indeed something that needs to be changed. This is the bottom that we want to change. Add variable is in title case, and we want to change that sentence case. So we go here.

A

We're gonna, remove that and then save it. Hopefully, that's gonna work out. I'm gonna refresh these.

A

To take a minute because GDK and GDK is not as fast cloudy block, it's your machine doing everything, so ah it failed. That's okay, that happens. Sometimes, that's probably because my machine is running many things right now, so I'm, just gonna refresh. If you see these, don't worry, okay, we're back!

A

That's good, I'm, open dribbles and there you go add variable right, perfect. Now we change that text as well all right. So, let's go back to our tutorial thing. The thing that we had at the beginning, I think we recover the finding the text in the local installation. We find the text you see in BS code. We determine what files need to be changed and we're gonna push the changes and opening them are. However, I'm gonna jump quickly to five, because there's okay, there's one tricky stab they recover in between which was the tests.

A

There's one more important thing that I gotta do is, and that thing is the translations. So any time that you change text in gridlock, you need to run out translation jobs that it's gonna hit to generate these. That Pio files that you see here, you don't have to change those yourself. That's gonna be generated, but not by an automated job.

A

In that you can run your might and I'll gonna explain you in a minute how you do it, but yeah just just have in mind that if you don't do that, if you don't run it translations, then your pipelines gonna fail because it meets those translations to work.

A

So how do you run those relations? It's not that hard used it to run one command which, by the way, I don't know, I, don't know which it is, but I always googled that so I always go to Google and I. Google. Something like gitlab, translation and I know that the job has something to do. We like like being rake or whatever so I, always like that. I know that that's part of the command, so that's how I search it.

A

This is the this is the page that I'm always looking for I should probably memorize these like save it somewhere else, but you can find in these way. As this way too, you wanna find one line of one command here and I'm gonna tell you which exactly it is to do. It's.

A

Somewhere, okay, this is the one so updating the Pio files with the new content. So we have new content. We got updated appeal files. The way that you do it is by running these. How do you run it? You go to your get lot. You can use your kidnapped er!

A

You go to your base code, you can use your terminal there or you can use your I term or your Mac terminal, whatever you want in this case, I'm gonna use this terminal when I make sure that I'm on the right place you gotta be in get lock inside the kidnap folder inside DDK I am the ion. I am on that one and I'm just gonna paste that and then I'm gonna run them, and this is gonna take a while. This is not fast. So it's ready thinking, don't worry.

A

If you don't see things happening there, that's usually what happens. It takes a minute.

A

I'm gonna probably pass forward these in the in the video when I'm editing, which yeah just know that it's definitely not fast, all right, so the translations are done.

A

So that's awesome. Now we're just gonna make sure that everything looks good. Everything looks good here. We have two files that we changed and we have a GUID lab that pod file that contains all the translations that we just did so we're good I'm going to create anymore for these. Just so, you see how on MRI it gets created for this type start, and just so you know, so you can see that there's nothing scary about creating a Lamar for code based changes, you're, not gonna, break anything.

A

It's totally, fine, just very mind that in a real case scenario, I wouldn't actually submit this a mark for review, because I'm making two changes in two completely different things and usually the way that we develop I did lab. We don't do that type of stuff. We actually just change one little thing, and then we submit anymore. For that and that's it. You know you don't wanna mix apples with pears, although these tax changes they are in different areas, different files. This is gonna trigger.

A

Different reviewers, like in like Jonah danger, is gonna ping and trigger different reviewers yeah. Not only not a good idea to submit any mark with these two changes, but I'm gonna do it just so. You see that it's quite easy and me just dismiss these, don't save all right.

A

So the way to do this is very simple. So, right now, as I said at the beginning of the tutorial, you want to have SSH setup. You don't have SSH. This is not gonna, be as easy, but because I have a safe set up a safe set up. It's going to be quite easy, so the only thing that I gotta do is basically commit. This I'm gonna get commit message.

A

Just make sure that you respect the conventions we have some conventions in you'd love when you create commit the first letter must be capitalized, don't add in a dot like any period like your message and another one is no more than 75 characters.

A

So what I'm, gonna name these commits is gonna, be something like updating text case and then, oh by the way, something that I didn't do please forget what I just need is something very important, something that I should have done from the beginning and it's my mistake, but you should create a new branch for these changes, which I'm gonna do right now, so I'm gonna before I commit anything. I'm gonna create a branch that it's called text.

A

Pixels UI and that's gonna fail because I never mind. Of course that's horrible!

A

Let me actually put my.

A

My user name there, ok so now, I'm now I switched on your branch now I'm good now, I'm gonna actually do the commits that I was doing before so get commit message.

A

Fixing text case and then of course, I forgot to add the file. Sorry about that. That's another thing that you gotta do I had done that you gotta add the files that you change week. You do that with keyed at period and now you can actually come in so you do get commit message fix in text days now three files change five insertions. Now you wanna push what's gonna happen.

A

Here is if I do get push, it's gonna say like hey, you cannot push yet because you need an upstream branch and I could do that right away, but I usually allowed the terminal to get. Tell me that and then I copy the command that they give me back so I. Basically just do it push origin, and it tells me this thing to push the current branch and set the remote as upstream use this. So I just copy this and paste that here and that's gonna generate the app steam.

A

The upstream branch, then I'm, gonna use cream. I'm Mayim are doing that. Who should be changes? It's coming it's happening and there you go now. We have an actual merge request. Url, where we can't work so I'm going to open that you just need to follow this link, so just do come on click here in this case open and that's gonna. Oh that's strange. Let me see why that happened.

A

Swim's that it's a problem we as I said at the beginning. Finding the hiccups didn't try this before. So that's pretty strange, okay, I know what what's going on. It's basically that I'm locked out for like something locked me out so I'm just gonna do.

A

Holy yes, open, okay, we're good! Now it's working okay! So as always, it's very important that you follow all our workflows and you respect the way that developers work, you're, doing developer, work, you're, not a developer, but you're doing developer work so make sure you follow what the template tells you to do.

A

Add screenshots necessary I'm, not going to do that for the sake of the tutorial there. Yeah just have that in mind. Also take like a meaningful title. Fixing.

A

Title case issues in settings and disease: let's say that this is a work in progress now and I'm gonna create it just the cities. You know I'm gonna assign this to me, doesn't matter and when I say that I wanna squash the comments when the merge requests is accepted, but the reason one when I create it is because I want to show you that nothing happens. I just need two changes and nothing's gonna happen, requests and you're, not gonna, break anything everything's.

A

Fine, it's gonna danger, it's gonna, rot its job and it's gonna suggest some reviewers, but danger is not gonna ping, the reviewers so you're totally fine you're, not like you know, creating an inconvenience for anyone here. This is just your work. You know.

A

Very importantly, you wanna make sure the the pipeline is running, which in this case is already running glass. Important thing here is I'm, not gonna. Wait for these pipeline to pass, but you wanna make sure that this pipeline is passing. If it fails, you gotta go and check lightly. What test it's failing when something fails, is likely a test or is likely danger.

A

Danger, bought the danger image which I don't know where it is exactly but danger is the border like coordinates, DMR, make sure that the M R is consistent with our practices and danger. Can't complain about your commute message. Can't complain about the way that you set up your M R and you just gotta pay attention to those things and perhaps fix those things. But there you go you you. We basically went through all these things.

A

We fix two pieces of text and it's now running a pipeline, and if these was successful and I added all the details, then I can ping. My reviewers and I can probably submit peaceful review and get this merge very soon. You know like likely with you're gonna. Look at it. Look at it quick and they're gonna, maybe maybe make a couple of suggestions, maybe not, but if they agree with the change, then that basically makes it to the next batch of deployment and then your once it's proved and moved to like the next environment.

A

Then your change might be in the codebase by like like in a couple of days or so like that night. Sometimes I, don't know how fast it is, but it's fast and yeah. That's that's everything. I have for you today. I think I really cover everything.

A

Just a quick recap make sure that you have the prerequisites before you do any of these and, very importantly, make sure that you are aware of the caveats and the tricky stuff. One report on caveat for sure is to have everything set up. Well, your beers cold and your macchina Eugenia K. You want to have all those things well set up the other one that I talked about it's the tests. I know that it wasn't super clear on that one, but I think you're gonna realize when those tests need to be changed.

A

I think it's quite evident. When you see those just make sure that you check for those files as well, it's files that any iNDOT spec that's power of the suffix of the file, and if you have doubts about that, you can message me or you can talk with your developers as well. If they know how to deal with this as well and yeah. The last freaky stuff is not really like a tricky stuff, but it's a requirement which is make sure that you run the translations.

A

If you don't run the translations, it's gonna fail the pipeline, because you don't you didn't do that and yeah that's it. I hope this was helpful. I hope it's not too long, but I want it to be very thorough.

A

If you have again, if you have questions just send me as like message and I'll be happy to help, you have a good one.