ContextQMD
Back to Gitlabhq

Lesson 1

doc/development/fe_guide/onboarding_course/lesson_1.md

18.11.29.4 KB
Original Source
<div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=k4C3-FKvZyI">Lesson 1 intro</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/k4C3-FKvZyI" frameborder="0" allowfullscreen> </iframe> </figure>

In this lesson you tackle the smallest of problems - a one-character text change. To do so, we have to learn:

  • How to set up a GitLab Development Environment.
  • How to navigate the GitLab code base.
  • How to create a merge request in the GitLab project.

After we have learned these 3 things, a GitLab team member will do a live coding demo. In the demo, they'll use each of the things learned by completing one of these small issues, so that you can complete an issue by yourself.

There is a list of issues that are very similar to the one we'll be live coding here in the "Linked items" section, it would be worth commenting on one of these now to get yourself assigned to one so that you can follow along.

What is the GDK?

<div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=qXGXshfo934">What is the GDK</a>? </div> <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/qXGXshfo934" frameborder="0" allowfullscreen> </iframe> </figure>

The GDK (GitLab Development Kit) is a local instance of GitLab that allows developers to run and test GitLab on their own computers. Unlike frontend only applications, the GDK runs the entire GitLab application, including the back-end services, APIs, and a local database. This allows developers to make changes, test them in real-time, and validate their modifications.

Tips for using the GDK:

  • Troubleshooting documentation: When encountering issues with the GDK, refer to the troubleshooting documentation in the GDK repository. These resources provide useful commands and tips to help resolve common problems.
  • Using the Rails console: The Rails console is an essential tool for interacting with your local instance of GitLab. You can access it by running gdk rails c and use it to enable or disable feature flags, perform backend operations, and more.
  • Stay updated: Regularly update your GDK by running gdk update. This command fetches the latest branch of the GitLab project, as well as the latest branch of the GDK and its dependencies. Keeping your GDK up to date helps ensure you will be working with the latest version of GitLab and make sure you have the latest bug fixes.

Remember, if you need further assistance or have specific questions, you can reach out to the GitLab community through our Discord or other available support channels.

Installing and using the GDK locally

<div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=fcOyjuCizmY">Installing the GDK</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/fcOyjuCizmY" frameborder="0" allowfullscreen> </iframe> </figure>

For the latest installation instructions, refer to the GitLab Development Kit documentation.

Here's a step-by-step summary:

  1. Prerequisites:
  2. Installation:

    • Choose a directory to install the GitLab Development Kit (GDK).

    • Open your terminal and go to the chosen directory.

    • Download and run the installation script from the terminal:

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

    • Only run scripts from trusted sources to ensure your safety.

    • The installation process may take around 20 minutes or more.

  3. Choosing the repository:
    • Instead of cloning the main GitLab repository, use the community fork recommended for wider community members.
    • Follow the instructions provided to install the community fork.
  4. GDK structure:
    • After the installation, the GDK directory is created.
    • Inside the GDK directory, you'll find the GitLab project folder.
  5. Working with the GDK:
    • GDK offers lots of commands you can use to interact with your installation. To run those commands you must be inside the GDK or GitLab folder.
    • To start the GDK, run the command gdk start in your terminal.
    • You can explore available commands and options by running gdk help in the terminal.

Remember to consult the documentation or seek community support if you have any further questions or issues.

<div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=Wc5u879_0Aw">How to navigate the GitLab codebase</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/Wc5u879_0Aw" frameborder="0" allowfullscreen> </iframe> </figure>

Understanding how to navigate the GitLab codebase is essential for contributors. Navigating the codebase and locating specific files can be challenging but crucial for making changes and addressing issues effectively. Here we'll explore a step-by-step process for finding files and finding where they are rendered in GitLab.

If you already know the file you are going to work on and now you want to find where it is rendered:

  1. Start by gathering clues to understand the file's purpose. Look for relevant information within the file itself, such as keywords or specific content that might indicate its context.
  2. You can also examine the file path (or folder structure) to gain insights into where the file might be rendered. A lot of routing in GitLab is very similar to the folder structure.
  3. If you can work out which feature (or one of the features) that this component is used in, you can then leverage the GitLab user documentation to find out how to go to the feature page.
  4. Follow the component hierarchy, do a global search for the filename to identify the parent component that renders the component. Continue to follow the hierarchy of components to trace back to a feature you recognize or can search for in the GitLab user docs.
  5. You can use git blame with an extension like GitLens to find a recent MR where this file was changed. Most MR's have a "How to validate" section that you can follow, if the MR doesn't have one, look for the previous change and until you find one that have validation steps.

If you know which page you need to fix and you want to find the file path, here are some things you can try:

  • Look for content that is unique and doesn't contain variables so that you can search for the translation variable.
  • Try using Vue Dev Tools to find the component name.
  • Look for unique identifiers like a data-testid,id or a unique looking CSS class in the HTML of the component and then search globally the codebase for those identifying strings.

Writing a good merge request

<div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=H5zozDNIn98">How to write a good MR</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/H5zozDNIn98" frameborder="0" allowfullscreen> </iframe> </figure>

When writing a merge request there are some important things to be aware of:

  • Your MR will become a permanent part of the documentation of the GitLab project. It may be used in the future to help people understand why some code works the way it does and why it doesn't use an alternative solution.
  • At least 2 other engineers are going to review your code. For the sake of efficiency (much like the code itself you have written) it is best to take a little while longer to get your MR right so that it is quicker and easier for others to read.
  • The MRs that you create on GitLab are available to the public. This means you can add a link to MRs you are particularly proud of to your portfolio page when looking for a job.
  • Since an MR is a technical document, you should try to implement a technical writing style. If you don't know what that is, here is a highly recommended short course from Google on Technical writing. If you are also contributing to the documentation at GitLab, there is a Technical Writing Fundamentals course available here from GitLab.

Live coding

<div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=BJCCwc1Czt4">Lesson 1 code walkthrough</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/BJCCwc1Czt4" frameborder="0" allowfullscreen> </iframe> </figure>

Now it is your turn to complete your first MR, there is a list of issues that are very similar to the one we just finished that need completing here in the "Linked items" section. Thanks for contributing! (if there are none left, let us know on Discord or other available support channels and we'll find more for you)