The pipeline editor is GitLab default tool for author and build your pipeline, previously the editor only worked if you are an existing users, new users would have to manually create a .gitlab-ci.yml configuration file before going into the editor, in this release we've added an empty state page to the pipeline editor which will allow you to create an empty pipeline file, providing you with an end to end experience without leaving the comfort of the editor.
Problem to solve
This is an MVC issue for the Pipeline Editor empty state.
The pipeline editor in its current form works only when a pipeline file is available.
MVC Proposal
In MVC approach we can start by addressing the scenario when there is no CI config file (whether it has a different name or doesn't exist).
In that scenario we should show an empty state when the user navigates to Pipeline Editor, whether they use the sidebar navigation or "Set up CI/CD" button from the repository.
The empty state shows a typical GitLab empty state with descriptive text, illustration and a CTA button.
CTA button when clicked creates a new file, and if there's no branch, it creates a branch. If there's no repo, it should create a repo.
The user it taken to a blank file in the Pipeline Editor, the file needs to be committed to create it.
@marcel.amirault I did my best to write clear and compelling UI copy, but would appreciate your extra magic! Check out the issue description.
I want to keep the copy focused on the feature and benefit. At the same time, we need to explain a bit about what's gonna happen when you click on the button. Those completely new to CI/CD may not even know it's configured in a YAML. After all there are CI/CD tools that have a complete UI. So the text should prepare them for what's to come.
cc @dhershkovitch I added a mock-up in the issue description, let me know what you think.
@nadia_sotnikova I've come back to this a few times, and I'm not sure the best thing to say here. I think the CTA is good, to start.
The notification is not bad, but I think this is really tricky. For instance, what if the example I use leads me to configure merge request pipelines to start? Then the line commit and run pipeline won't be true, because the pipeline won't run (at least, not until we can create MRs from here). You could also use a template, as you note, or just configure it by hand...
This is just a very rough guess, but how about something like:
Configure your CI/CD pipeline
Enter GitLab CI/CD configuration below and commit it to start running pipelines. You can apply a template, copy from the [CI/CD examples](examples link), or [configure it from scratch](reference link).
For instance, what if the example I use leads me to configure merge request pipelines to start? Then the line commit and run pipeline won't be true, because the pipeline won't run (at least, not until we can create MRs from here). You could also use a template, as you note, or just configure it by hand...
The lint status having a new copy for empty state is better done separately
The banner can be done in multiple ways, 2 of which would only require frontend and are fairly easy to do
I don't think we can have an uncommitted empty file to someone to work on, and then commit. We need to commit the empty file, then let the user edit it.
We might have to handle only one case first (no file, but have a repository) because the other case implementation will require a deeper analysis on how to do it (create a repository and branch in the background).
After these are address, ping me again and I will assign a weight for what we chose
@dhershkovitch I wanted to discuss two improvements for that experience (see the mock-ups in the issued description):
When the new file is created, it'll be empty. We shouldn't say "Configuration is invalid" at that point in the status section, it'll be confusing to new users. In the mock-up I proposed to show a special status for when there's no content in the file. Should it be a separate issue?
When a user with an existing configuration opens the Pipeline Editor for the first time, we'll be showing this welcome alert, prompting for feedback. I think we need to show a welcome alert in this case too, but the content needs to be tailored to the new CI/CD users. Something like this. Should this also be a follow-up?
When the new file is created, it'll be empty. We shouldn't say "Configuration is invalid" at that point in the status section, it'll be confusing to new users. In the mock-up I proposed to show a special status for when there's no content in the file. Should it be a separate issue?
Yes, since the validation relies on the lining API's
When a user with an existing configuration opens the Pipeline Editor for the first time, we'll be showing this welcome alert, prompting for feedback. I think we need to show a welcome alert in this case too, but the content needs to be tailored to the new CI/CD users. Something like this. Should this also be a follow-up?
I believe it could be a part of the mock, but its best to ask one of the engineers
@f_caplette In the issue description I proposed a design for the empty state MVC. It'd be great to show a welcome alert to new users who don't have any configuration. Is it something we can add in the same iteration? Otherwise, landing into the empty editor without any guidance isn't very helpful. Eventually we'll be adding more guidance to the drawer, but for now an alert would go a long way. It's also an opportunity to gather feedback (the alert will link to a feedback issue).
In the mockup you'll see I also added an empty state for the validation status section. This can be a follow-up iteration.
@nadia_sotnikova I have a couple of questions regarding the banner
Do we show it when you have an empty file, or just an empty root file? With file and branch selection coming soon, I think this need to be clarified right away. If we want to show this on load for any empty file, that's very easy and FE only. If we want to show this whenever you have an empty root file on any branch, then we need a way to know it's the root file, which might require some backend.
The other option would be to show the banner after the redirect, but I am not a fan because if you created an empty file already and go to the section, the banner would still useful. If we went this route, it would mean adding a query param to the url to show this banner.
So in short:
The banner can be in the MVC if it's shown for any empty file. This would be frontend only and is very easy to do (if the initial loaded content is empty, show banner)
Showing the banner only for an empty root configuration would require to dig further, its less likely to make it in the MVC and might require some backend work to determine if it's the root CI config
Showing the banner just after the redirect (so after creating the file) would be doable with just frontend but I am not sure it's the best solution
A couple of other points
The user it taken to a blank file in the Pipeline Editor, the file needs to be committed to create it.
I am not sure if this is doable to be honest I think we need to create and commit the new file before you can start editing it as the editor lite require a file path to work and have the syntax highlight. Even the WebIDE will ask you to create the file first and then you can edit and commit the changes.
CTA button when clicked creates a new file, and if there's no branch, it creates a branch. If there's no repo, it should create a repo.
For the MVC, we might have to support only the first case, which is that you have a repository and a branch, but no file. The reasoning is that I am not sure how we currently create these in the background and it will require additional investigation. I would love to propose to do it in steps: Let's aim to have at least that first use case cover, and then add the use case when there are no repository created. Also, I think that if you have a repository, you absolutely have a branch, and if you have a branch, you have a repository. To be confirmed!
I am not sure if this is doable to be honest I think we need to create and commit the new file before you can start editing it as the editor lite require a file path to work and have the syntax highlight. Even the WebIDE will ask you to create the file first and then you can edit and commit the changes.
Interesting, this is not the case with the single file editor, when in a blank project
I can click on the setup CI/CD
but then if i hit cancel the project remains empty
the Web ide asks me to create a file
but then again, if I do not commit changes
I can discard them, and then go back to the blank project
Regarding the banner, i would recommend we use the easiest possible way to implement it.
Do we show it when you have an empty file, or just an empty root file? With file and branch selection coming soon, I think this need to be clarified right away. If we want to show this on load for any empty file, that's very easy and FE only. If we want to show this whenever you have an empty root file on any branch, then we need a way to know it's the root file, which might require some backend.
The idea is to only show this banner when the user clicks on "Create new CI/CD pipeline" and lands in the Pipeline Editor. It'll be a one time banner that will never show up once dismissed.
As @dhershkovitch mentioned above, we want to achieve the same experience that single file editor provides when you click on the "Set up CI/CD" in your repository. Clicking this CTA takes you to the file right away where you can apply a CI template and commit to run your pipeline without any other extra steps. In our case, you'd click on the CTA in the empty state, and land in Pipeline Editor with an empty .gitlab-ci.yml file ready to be committed. The user applies a template and commits the file, which runs their first pipeline.
For the MVC, we might have to support only the first case, which is that you have a repository and a branch, but no file. The reasoning is that I am not sure how we currently create these in the background and it will require additional investigation. I would love to propose to do it in steps: Let's aim to have at least that first use case cover, and then add the use case when there are no repository created.
@dhershkovitch@nadia_sotnikova After investigating deeper, everything around the single file editor and creating branch/repository is made in ruby (HAML) and we can't simply reuse what we already have. The most likely solution is to add graphQL mutations so that we can create a new branch and repository. If we can have both done in the same milestone, great! I just assumed that we could split the work in two and do it progressively. This will require some backend as well.
Set up CI/CD" in your repository. Clicking this CTA takes you to the file right away where you can apply a CI template and commit to run your pipeline without any other extra steps. In our case, you'd click on the CTA in the empty state, and land in Pipeline Editor with an empty .gitlab-ci.yml file ready to be committed. The user applies a template and commits the file, which runs their first pipeline.
If both the single file editor and the WebIDE are able to do this, then it should be fine here too. Once we are ready to implement all of this I will investigate how to handle this use case
Also I believe we should probably work on the banner in a separated issue wdyt?
@f_caplette @lauraMon Can I ask you to collaborate on weighting and refining this issue (as needed) for %13.10? Feel free to split off a separate backend task if you feel it's helpful.
frontend Allow users to start working in the editor lite if they have a repository but no root Ci config file or no repository. I have realized that this part is just as easy for both use cases, but the complexity comes later when we commit.
backendfrontend It seems that getCiConfigQuery returns an error currently when working off an uncommitted file (See bottom images). Investigate the problem in collaboration between frontend and backend
backend Add a graphQL mutation that allow the user to create a file. Question Do we use the same commit mutation we are already using and it will take care of that for us, or do we need to know if it's a new file and call a different mutation?
backend Ideally, the mutation to create a file would also create the repository in the background if necessary. If not and we need two separate mutation, then we need the following point instead
backend Add a graphQL query to know if a repository exists in the project. This is not necessary if we can have a single mutation for the commit and repository
frontend Call the mutations to create a new file if required so we need to keep track
@dhershkovitch So in essence, a user will have the same editing experience regardless of the fact that they have or don't have an existing file/repository because we don't commit the file initially, so both usecase have to be supported together for this to ship. The burden then is place more on the backend work: we need a graphQL mutation that does both the commit and repository because we allow both type to create an uncommitted file and start working without distinction.
@cheryl.li we do have an epic already, so i believe its fine to break this into additionals issue and add to the epic, also, i will update the epic description to reflect the current proposal.
backend Add a graphQL query to know if a repository exists in the project. This is not necessary if we can have a single mutation for the commit and repository
Is something that backend team should answer, right?
@dhershkovitch Yes exactly. Ideally we would have a single mutation on the FE that sends the file content and the commit, and the API would see if it needs to create the repository and or a new file. But if for some reason they need to be separate graphQL mutations, then there will be a bit more work frontend side.
@f_caplette This was an awesome list, thank you so much
backendfrontend It seems that getCiConfigQuery returns an error currently when working off an uncommitted file (See bottom images). Investigate the problem in collaboration between frontend and backend
Let's look into this together and we can create a separate issue for it.
backend Add a graphQL mutation that allow the user to create a file. Question Do we use the same commit mutation we are already using and it will take care of that for us, or do we need to know if it's a new file and call a different mutation?
the createCommit mutation seems to require a repository so we may not be able to reuse it as is. I wonder if we could modify it though, and add in the check somewhere in there. That way we may be able to do:
backend Ideally, the mutation to create a file would also create the repository in the background if necessary. If not and we need two separate mutation, then we need the following point instead
with the import_service from projects, which adds a repository to a project. I think it's worth it for us to try to go this route to keep things simpler, even if it requires a bit more work. WDYT?
@dhershkovitch@cheryl.li Since we've got some reimplementing to do to use the same mutation a few small unknowns, I think this is a lowish backend-weight3 - might end up being a 2.
Should I go ahead and create the backend implementation issue with this info?
@lauraMon It sounds like there's a fair bit of detail in the re-implementation work (and possibly explore a 'few small unknowns') - maybe a separate issue would be easier to keep things separate. I'd leave it to you and @f_caplette to decide what's the best way to represent this work.
@lauraMon
I also support opening a separate issue but leave it up to you, if you end up opening another issue make sure to ping me so i will apply the labels
@dhershkovitch I copied over the labels from this one but I pinged you anyway in case you want to update :) It's not very verbose but I think it has the necessary details for someone to work on it.
@dhershkovitch I want to make sure I'm not missing anything here in terms of UX that needs to be addressed.
User sees an empty state
Once clicking on the CTA we will redirect the user to an empty .gitlab-ci.yml file
The user should be able to update its configuration the visualization/linting/merged YAML view should all work
If the user tries to navigate away from the editor without hitting the commit button we should prompt a warning message, that changes will be lost
If the user hit the commit button we should create the file and the repo
This all sounds great to me. Should I create a separate issue for this alert? It's a special alert that only new users will see after they click on the empty state CTA and it'll help us gather feedback + guide the user a bit before we add the drawer with documentation.
Should I create a separate issue for this alert? It's a special alert that only new users will see after they click on the empty state CTA and it'll help us gather feedback + guide the user a bit before we add the drawer with documentation.
@nadia_sotnikova I agree to make this a separate issue. I think it's a nice to have and hopefully we can do it in the same milestone, but it will be easier to address on its own.
@dhershkovitch@samdbeckham I made the first MR for this issue which changes the error alert for the empty state without any CTA. This is easier to work with and be reviewed first. Once this is merged, the subsequent MR will add the CTA and the ability to commit your file even if you don't have a file or a repository.
I'll keep you updated, but if we think it won't make it in the milestone, there is a way to only allow user with a repository but without a CI config file to start working that we can discuss.
@cheryl.li Short answer, yes we need it to ship the empty state MVC.
Long answer:
I found this issue after I completed the FE for this issue. It's actually getting merged today behind a disabled feature flag, so it's good to go This issue is that we can't lint at all if you have no repository. It therefore prevent us from allowing a user in our section if they have no repository because they wouldn't get any linting (which is fairly important) and they'd see a bunch of unrelated errors everytime they type.
If we can't get to it in %13.10, we can add a check in the FE to only allow user to get started if they have a repo. So if they have a repository, but no CI config file, it would work. Obviously it's not ideal, but it would be simple enough to do and it would already allow more user to get started.
After working on the backend issue in parallel with the bug/"not bug but feature" fix (#323223 (closed)) I realized that the work that is needed is all in the frontend implementation for the mutation, not the backend. Fréd and I chatted about this and I've updated the issue to reflect that.
I will keep working on the bug fix since we have to get that fixed in order to get this to work.
Why "not bug but feature?"
The lint endpoint requires a sha to work. With this feature, when we create a project, an empty repository with nothing else gets created. So we do not have a commit or a sha.
@samdbeckham It's additional work. I can create an issue for it, but I planned having an MR for it soon (probably today) and I would add it to this issue since it should have been part of the same work, it's just we didn't realize it had to be done. Let me know if that make sense!
edit: Actually the MR is done and is sent to review. Here it is: !56009 (merged)
@dhershkovitch@nadia_sotnikova The Empty state MVC is done and has been turned on for staging. My goal is to turn it on today on production as well (waiting a bit to make sure the production incident is over) and tomorrow merge it as on by default if everything looks good. Please go on and test it when you can before I turn it on by default to let me know if everything works as you expect. It works for me both for new file with and without a repo. Here is the flag rollout plan #323229 (closed)
My GDK is broken so I'm not able to test it locally. Screenshots look good, and I'll have to trust you and @dhershkovitch that everything works as intended.
P.S: Is there some other way to test this other than in the GDK? Asking for the future.
@dhershkovitch@nadia_sotnikova Thanks for checking! I enabled it on .com now so it's on production! Since it's pretty straightforward, it seems good to enable by default for self hosted today. I am still going to wait a bit for people to play around (I'll ask a couple of people to check on prod if they create a new project). I should merge !56665 (merged) today