Community Article: First Contribution Experience

I’d like to post an article from a team member of ours, Oksana :grin: Thanks for your contribution, Oksana!

(Article follows)

For a long time, I was an observer of the open source landscape, admiring the dedication of countless contributors who poured their expertise into projects accessible to anyone.

It was always interesting how everything was put together.

And then, it happened — I joined GitLab, an organization wholly committed to the open source ethos.

Today, I am excited to share my journey into the open source that began with my very first contribution, an experience that deeply inspires.

This journey is not just mine.

It’s an invitation to all those who, like me, spent time wondering how to start and if they could ever become part of this great community.

Spoiler alert: You absolutely can!

Let’s begin!

Every time I step into a new project, I am curious about three things:

  • how to set up my development environment

  • how to debug the product effectively

  • what the code review process looks like

While the former is a one-time setup, the latter two become daily companions.

Let’s discover together how it works in GitLab.

Setting Up the Local Development Environment

GDK Setup

As I delved into GitLab, I discovered a well-crafted documentation that became my guiding light.

So, while searching through the documentation of how to get started, I found a Tutorial: Make a GitLab contribution which provides everything what a first-time contributor like me needed.

Step one was to request access to the GitLab community fork. Access was granted almost immediately — thank you, team!

The next interesting part was to setup the GitLab Development Kit (GDK) and run a self-managed GitLab instance locally.

With access in hand, I embarked on A new GDK installation.

I followed the instructions and few troubleshooting docs in hand (Troubleshooting GDK and Troubleshooting asdf).

Then running gdk start and the GitLab website was up without any errors.

An impressively fast setup that allowed me to start contributing within hours!

Finding the First Issue

Next up, is the quest to find the perfect issue to tackle.

In the change the code section, I discovered a good example of how to make a code change, commit, and create a merge request.

The task was simple: fix a Learn more link.

A teammate also shared a tutorial in a video format of the same task (I highly recommend watching those videos as James shares useful tips and recommendations there).

That tutorial led me to a list of issues perfect for first-time contributors.

Another approach was to browse the issues board, filtering for issues labeled ~Seeking community contributions and ~quick win. I like how easy it is to find issues suited to any skills and interests, be it backend, frontend, devops, or maintenance.

I chose the first open issue from the Standardise ‘Learn more’ links list.

Making a Contribution

Now, let’s dive into the process of making a contribution.

First, I reviewed the issue to understand what needs to be done.

The description contained clear instructions on the required changes.

It was also detailed in the tutorial.

The task involved modifying the Vue component app/assets/javascripts/token_access/components/outbound_token_access.vue to ensure the link is displayed correctly.

Reviewing the component file, I located the Learn more link and moved a full stop out of it as per the issue’s instructions.

Now a challenge was to find the page in the UI where this component is rendered and verify that the fix works.

The first thing I always check is the file name as it usually reflects the object/page/service/etc it’s created for. In this case, it is Outbound Token Access.

So, I expect a menu item with this name or similar to be somewhere in the UI.

Then I noticed the translation string with the Learn more link — it starts with the CI/CD prefix:

CICD|Prevent CI/CD job tokens from this project from being used to access other projects unless the other project is added to the allowlist. It is a security risk to disable this feature, because unauthorized projects might attempt to retrieve an active token and access the API. %{linkStart}Learn more%{linkEnd}.

It got me to find a CI/CD page in the UI. I went to the site and selected one of the projects.

And here it was, a CI/CD page in the right sidebar. I followed it and the only section that had a similarity with Outbound Token Access was Token Access.

I clicked the Expand button in front of it and the text with the needed Learn more link is displayed in the second section. Hooray!

However, I noticed a minor alignment issue after my code change — the full stop appeared at the end of the paragraph rather than after the link.

To resolve this, I reviewed the component’s template and attempted to adjust it. First, I moved the line out of the initial <template> tag, which didn’t work. Then, I shifted it out of the subsequent <gl-sprintf> tag, and voila! The full stop now followed the Learn more link as expected.

There was still another minor issue — a space between the link and the full stop. This was likely due to placing the content on its own line within the tag.

I changed the text interpolation code into a single line instead of three which resolved the issue.

With the text now in order, I ran bin/rake gettext:regenerate, as suggested, to automatically update the locale/gitlab.pot localization file.

I found more details about how localization works at GitLab on Internationalization page.

Satisfied with the fix, I committed the changes and pushed them to GitLab.

In the MR template, I provided before-and-after screenshots to help reviewers quickly grasp the issue and its resolution. Additionally, I outlined validation steps for the fix’s verification, ensuring that reviewers could easily confirm it’s working if necessary. With this, I hit the Create MR button.

While the issue only requested moving the full stop out of the link, I addressed the alignment issues as well.

To save time and streamline communication with the reviewers, I added comments to the code lines with the screenshots, explaining the rationale behind each change and its impact if not implemented.

When the pipelines went green, the MR was ready for review. I assigned the reviewers that were suggested by the Reviewer roulette. I find it a super helpful bot that saves you time in finding the right reviewer.

Within two days, the merge request received approval and was merged, marking the successful closure of my first issue. A smooth experience, with clear guidelines and responsive reviewers, made this achievement possible.

Debugging Rails

The last question related to debugging the GitLab application with pry while it ran in the foreground.

Simply putting binding.pry, as I used to, did not work.

I found two valuable resources addressing debugging: Pry debugging and VS Code debugging.

VS Code debugging

I decided to start with the VS Code setup, though it was a fairly new IDE to me.

I installed the VSCode rdbg Ruby Debugger extension and attempted to run the debugger.

While it worked intermittently, I encountered occasional freezes.

Uncertain about the root cause, I reached out to a teammate who suggested it might be an excellent topic for the community pairing session.

Afterward, I posted a query in the Discord pairing channel to cover debugging tool setups in an upcoming session.

We indeed looked into the debugging tool setup during the session where we set up ad tried Pry debugging and VS Code debugging.

For VS Code debugging, the main trick was to put tasks.json and launch.json into the right .vscode/ folder.

Those files should be added in gitlab-development-kit/gitlab/.vscode/.

Then to test it after the session, I went to the Run and Debug panel in VS Code and clicked Attach with rdbg in the Debug current file dropdown.

I put breakpoints in the gitlab-development-kit/gitlab/app/controllers/projects_controller.rb file in the def show action. Then visited http://localhost:3000/flightjs/Flight project page.

The debugging session was up!

Pry-shell debugging

No setup was needed for the pry-shell as this gem is already in the Gemfile.

To test binding.pry_shell, I put binding.pry_shell on the same line I had breakpoints for the rdbg debugging.

Then restarted GDK, opened a new terminal window, and ran pry-shell.

Reloaded the page and the debugging session appeared in the terminal. Yay!

So, now I have two ways of debugging.

With my development environment configured, merge request experience gained, and debugging tools set up, I’m ready to continue contributing.


My journey was nothing short of delightful. I’m deeply impressed by the quality of the documentation, community help, and how smoothly everything was.

If you’ve been waiting for a sign to embark on your open source journey, consider this it! Open source contribution offers tremendous opportunities for skill development, networking, and giving back to the community. Whether it’s picking up your first issue or bringing your unique feature idea to life, you can start contributing, collaborating with talented minds, and making your mark today. And should you encounter any issues the GitLab community is here to help.

Let’s open source together!