gitlab-ce/doc/development/contributing/first_contribution.md

stage	group	info
none	unassigned	Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.

Tutorial: Make a GitLab contribution

Anyone can contribute to the development of GitLab.

Maybe you want to add functionality that you feel is missing. Or maybe you noticed some UI text that you want to improve.

This tutorial will walk you through the process of updating UI text and related files using Gitpod or the GitLab Development Kit on the GitLab community fork. You can follow this example to familiarize yourself with the process.

NOTE: Join the GitLab Discord server, where GitLab team members and the wider community are ready and waiting to answer your questions and ensure everyone can contribute.

Before you begin

• If you don't already have a GitLab account create a new one. Confirm you can successfully sign in.
• Request access to the community forks, a set of forks mirrored from GitLab repositories in order to improve the contributor experience.
  • For more information, read the community forks blog post.
  • The access request will be manually verified and should take no more than a few hours.
  • If you use a local development environment, you can start making changes locally before your access is granted. You must have access to the community fork to push your changes to it.

Choose how you want to contribute

The two methods outlined in this tutorial cover:

• GitLab Development Kit (GDK)
  • Local development environment.
  • It's just like an installation of self-managed GitLab. It includes sample projects you can use to test functionality, and it gives you access to administrator functionality.
• Gitpod - Most contributors should use this option.
  • Remote development environment that runs the GDK remotely, regardless of your local hardware, operating system, or software.
  • Make and preview remote changes in your local browser.

The steps for each method vary in time and effort. You should choose the one that fits your needs.

::Tabs

:::TabTitle Gitpod - Remote environment

• Configure the remote development environment
• Change the code
• Create a merge request
• Complete the review process

:::TabTitle GDK - Local environment

• Configure the development environment
• Change the code
• Create a merge request
• Complete the review process

::EndTabs

Configure the development environment

In this section, set up the GitLab development environment locally or through Gitpod to make changes to the code.

Use Gitpod to contribute without a local environment setup

Set aside about 15 minutes to launch the GDK in Gitpod.

1. Launch the GDK in Gitpod.

2. Select Continue with GitLab to start a Gitpod environment for this fork.

3. If this is your first time using Gitpod, create a free account and connect it to your GitLab account:

   1. Select Authorize when prompted to Authorize Gitpod.io to use your account?.
   2. On the Welcome to Gitpod screen, enter your name and select whether you would like to Connect with LinkedIn or Continue with 10 hours per month.
   3. Choose the Browser version of VS Code when prompted to Choose an editor.
   4. Continue through the settings until the New Workspace screen.

4. On the New Workspace screen, before you select Continue:

   • Leave the default repository URL: gitlab.com/gitlab-community/gitlab/-/tree/master/.

   • Select your preferred Editor.

     The examples in this tutorial use Visual Studio Code (VS Code) as the editor, sometimes referred to as an integrated development environment (IDE).

   • Leave the default Class: Standard.

5. Wait a few minutes for Gitpod to launch.

   You can begin exploring the codebase and making your changes after the editor you chose has launched.

6. You will need to wait a little longer for GitLab to be available to preview your changes.

   When the GitLab GDK is ready, the Terminal panel in Gitpod will return a URL local to the Gitpod environment:

   => GitLab available at http://127.0.0.1:3000.
   

   Select the http://127.0.0.1:3000 to open the GitLab development environment in a new browser tab.

7. After the environment loads, log in as the default root user and follow the prompts to change the default password:

   • Username: root
   • Password: 5iveL!fe

After the Gitpod editor is ready, continue to Change the code with Gitpod.

Install and configure GitLab Development Kit (GDK)

NOTE: Skip this step if you're using Gitpod.

If you already have a working GDK, update it to use the community fork.

Set aside about two hours to install the GDK. If all goes smoothly, it should take about an hour to install.

Sometimes the installation needs some tweaks to make it work, so you should also set aside some time for troubleshooting. It might seem like a lot of work, but after you have the GDK running, you'll be able to make changes much more often and more easily.

View an interactive demo of this step.

To install the GDK:

1. Ensure you're on one of the supported platforms.

2. Confirm that Git is installed, and that you have a source code editor.

3. Choose the directory where you want to install the GDK. The installation script installs the application to a new subdirectory called gitlab-development-kit.

   Keep the directory name short. Some users encounter issues with long directory names.

4. From the command line, go to that directory. In this example, create and change to the dev directory:

   mkdir ~/dev && cd "$_"
   

5. Run the one-line installation command:

   curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/install" | bash
   

6. For the message Where would you like to install the GDK? [./gitlab-development-kit], press Enter to accept the default location.

7. For the message Which GitLab repo URL would you like to clone?, enter the GitLab community fork URL:

   https://gitlab.com/gitlab-community/gitlab.git
   

8. For the message GitLab would like to collect basic error and usage data, choose your option based on the prompt.

   While the installation is running, copy any messages that are displayed. If you have any problems with the installation, you can use this output as part of troubleshooting.

9. After the installation is complete, copy the source command from the message corresponding to your shell from the message INFO: To make sure GDK commands are available in this shell:

   source ~/.asdf/asdf.sh
   

10. Go to the directory where the GDK was installed:

    cd gitlab-development-kit
    

11. Run gdk truncate-legacy-tables to ensure that the data in the main and CI databases are truncated, then gdk doctor to confirm the GDK installation:

    gdk truncate-legacy-tables && gdk doctor
    

    • If gdk doctor returns errors, consult the Troubleshoot GDK section.
    • If gdk doctor returns Your GDK is healthy, proceed to the next step.

12. Start the GDK:

    gdk start
    

13. Wait for GitLab available at http://127.0.0.1:3000, and connect to the GDK using the URL provided.

14. Sign in with the username root and the password 5iveL!fe. You will be prompted to reset your password the first time you sign in.

15. Continue to Change the code with the GDK.

Troubleshoot GDK

If you encounter issues, go to the gitlab-development-kit/gitlab directory and run gdk doctor.

If gdk doctor returns Node or Ruby-related errors, run:

yarn install && bundle install
bundle exec rails db:migrate RAILS_ENV=development

For more advanced troubleshooting, see the troubleshooting docs and the #contribute channel on Discord.

Update an existing GDK installation

If you have an existing GDK installation, you should update it to use the community fork.

1. Delete the existing gitlab-development-kit/gitlab directory.

2. Clone the community fork into that location:

   cd gitlab-development-kit
   git clone https://gitlab.com/gitlab-community/gitlab.git
   

To confirm it was successful:

1. Ensure the gitlab-development-kit/gitlab directory exists.
2. Go to the top gitlab-development-kit directory and run gdk stop and gdk start.

If you get errors, run gdk doctor to troubleshoot. For more advanced troubleshooting, continue to the Troubleshoot GDK section.

Change the code

Now for the fun part. Let's edit some code.

In this example, I found some UI text I'd like to change. In the upper-right corner in GitLab, I selected my avatar and then Preferences. I want to change Customize the color of GitLab to Customize the color theme of the GitLab UI:

Change code with Gitpod

1. Create a new branch for your changes:

   Select master in the status bar, then from the Select a branch or tag to checkout box, select Create new branch and enter a name for the new branch.

   If your code change addresses an issue, start the branch name with the issue number.

   The examples in this doc use a new branch called ui-updates.

2. Search the repository for the string Customize the color of GitLab:

   • In VS Code, select the search icon from the side toolbar.

3. Select the app/views/profiles/preferences/show.html.haml file.

4. Update the string to Customize the color theme of the GitLab UI.

5. Save your changes.

6. Use the IDE Terminal tab to commit the changes:

   git commit -m "Update UI text
   
   Standardizing the text on this page so
   that each area uses consistent language."
   

   Follow the GitLab commit message guidelines.

7. Push the changes to the new branch:

   git push --set-upstream origin ui-updates
   

8. You can create a merge request with the code change, or continue to update the translation files.

Change code with the GDK

Use your local IDE to make changes to the code within the GDK directory.

View an interactive demo of this step.

1. Create a new branch for your changes:

   git checkout -b ui-updates
   

2. Search the gitlab-development-kit/gitlab directory for the string Customize the color of GitLab.

   The results show one .haml file and several .po files.

3. Open the app/views/profiles/preferences/show.html.haml file.

4. Update the string from Customize the color of GitLab to Customize the color theme of the GitLab UI.

5. Save the file.

6. You can check that you were successful:

   In the gitlab-development-kit/gitlab directory, type git status to show the file you modified:

           modified:   app/views/profiles/preferences/show.html.haml
   

7. Refresh the web browser where you're viewing the GDK. The changes should be displayed. Take a screenshot.

   

8. Commit the changes:

   git commit -a -m "Update UI text
   
   Standardizing the text on this page so
   that each area uses consistent language."
   

   Follow the GitLab commit message guidelines.

9. Push the changes to the new branch:

   git push --set-upstream origin ui-updates
   

10. You can create a merge request with the code change, or continue to update the translation files.

Update the translation files

English UI strings are localized into many languages. These strings are saved in a .pot file, which must be regenerated any time you update UI text.

To automatically regenerate the localization file:

1. Ensure you are in the gitlab-development-kit/gitlab directory.

2. Run the following command:

   tooling/bin/gettext_extractor locale/gitlab.pot
   

   The .pot file will be generated in the /locale directory.

   Now, in the gitlab-development-kit/gitlab directory, if you type git status you should have both files listed:

           modified:   app/views/profiles/preferences/show.html.haml
           modified:   locale/gitlab.pot
   

3. Commit and push the changes.

4. Create a merge request or continue to update the documentation.

For more information about localization, see internationalization.

Update the documentation

Documentation for GitLab is published on https://docs.gitlab.com. When you add or update a feature, you must update the docs as well.

1. To find the documentation for a feature, the easiest thing is to search the docs site. In this case, the setting is described on this documentation page:

   https://docs.gitlab.com/ee/user/profile/preferences.html
   

2. The URL shows you the location of the file in the /doc directory. In this case, the location is:

   doc/user/profile/preferences.md
   

3. Go to this location in your local gitlab repository and update the .md file and any related images.

   Now when you run git status, you should have something like:

           modified:   app/views/profiles/preferences/show.html.haml
           modified:   doc/user/profile/img/profile-preferences-syntax-themes.png
           modified:   doc/user/profile/preferences.md
           modified:   locale/gitlab.pot
   

4. Commit and push the changes.

5. Create a merge request or continue to update the documentation.

Create a merge request

Now you're ready to push changes from the community fork to the main GitLab repository!

View an interactive demo of this step.

1. Go to the community fork on GitLab.com. You should see a message like this one:

   

   Select Create merge request. If you don't see this message, on the left sidebar, select Code > Merge requests > New merge request.

2. Take a look at the branch names. You should be merging from your branch in the community fork to the master branch in the GitLab repository.

   

3. Fill out the information and then select Save changes. Don't worry if your merge request is not complete.

   If you don't want anyone from GitLab to review it, you can select the Mark as draft checkbox. If you're not happy with the merge request after you create it, you can close it, no harm done.

4. Select the Changes tab. It should look something like this:

   

   The red text shows the code before you made changes. The green shows what the code looks like now.

5. If you're happy with this merge request and want to start the review process, type @gitlab-bot ready in a comment and then select Comment.

   

Someone from GitLab will look at your request and let you know what the next steps are.

Complete the review process

After you create a merge request, GitLab automatically triggers a CI/CD pipeline that runs tests, linting, security scans, and more.

Your pipeline must be successful for your merge request to be merged.

• To check the status of your pipeline, at the top of your merge request, select Pipelines.
• If you need help understanding or fixing the pipeline, in a comment, use the @gitlab-bot help command.

Getting a review

GitLab will triage your merge request automatically. However, you can type @gitlab-bot ready in a comment to alert reviewers that your MR is ready.

• When the label is set to workflow::ready for review, a developer reviews the MR.
• After you have resolved all of their feedback and the MR has been approved, the MR is ready for merge.

If you need help at any point in the process, type @gitlab-bot help in a comment or initiate a mentor session on Discord.

When the merge request is merged, your change becomes part of the GitLab codebase. Great job! Thank you for your contribution!