Tutorial: Make Your First Contribution to EBRAINS

In this tutorial, you’ll make your first contribution to an EBRAINS project on GitLab. You’ll learn the complete workflow from setting up Git to getting your changes merged.

What you’ll do: Fix a typo in the EBRAINS Handbook and submit it as a merge request.

Time required: 30-45 minutes

Prerequisites:

  • An EBRAINS account with GitLab access
  • Basic command line familiarity
  • A text editor installed

1. Understanding EBRAINS GitLab

EBRAINS GitLab is where all EBRAINS code, documentation, and projects live. It provides:

  • Version Control: Track every change with Git
  • Continuous Integration: Automatic testing of your code
  • Project Management: Issues, merge requests, and milestones
  • Collaboration: Work with researchers and developers across EBRAINS

Let’s dive in and make your first contribution!

2. Set Up Your Development Environment

Install Git

If you don’t have Git installed, follow these guides:

Verify your installation:

You should see output like: git version 2.39.0

Set Up SSH Key for GitLab

SSH keys allow secure authentication without entering passwords repeatedly.

Generate an SSH key:

Press Enter to accept the default file location, then optionally set a passphrase.

Copy your public key:

Add it to GitLab:

  1. Go to GitLab SSH Keys
  2. Paste your public key in the “Key” field
  3. Add a title like “My Laptop”
  4. Click “Add key”

3. Clone the EBRAINS UI Ecosystem Repository

Now let’s get the code on your computer:

If you encounter permission issues, try with your username:

You’ll be prompted for your personal access token as the password.

4. Create Your Feature Branch

EBRAINS uses a structured branching strategy. Before making changes, create a new branch:

Branch naming convention:

<type>/<app>/<task-id>

Common types:

  • feature/ - New features or enhancements
  • hotfix/ - Urgent fixes
  • chore/ - Non-functional updates

Create your branch:

This creates a new branch and switches to it.

Tip: For real projects, create a GitLab issue first and reference it in your branch name like feature/handbook/123

5. Make Your Changes

Let’s fix a typo in the handbook. Navigate to the handbook content:

Find a file to edit. For this tutorial, let’s edit the tools-and-resources introduction:

Make a small improvement:

  • Add a helpful search note

For example, you might add a helpful tip or improve wording.

Save your changes.

6. Check What Changed

Before committing, review your changes:

This shows which files you modified (in red).

See the specific changes:

Lines you removed will show in red with -, lines you added in green with +.

7. Stage Your Changes

Add your changes to the staging area:

Or add all changed files:

Verify:

Your files should now appear in green (staged for commit).

8. Create a Proper Commit

EBRAINS uses Conventional Commits for consistent commit messages.

Commit Message Format

<type>(<scope>): <short description>

Create Your Commit

For our typo fix, we’ll use the docs type:

Breaking it down:

  • -m "docs(handbook): fix typo..." - Subject line (type, scope, description)
  • -m "Changelog: added" - Trailer (required for EBRAINS)

9. Push Your Branch to GitLab

Now send your changes to GitLab:

You’ll see output confirming the push and a URL to create a merge request.

10. Create a Merge Request

Via the URL (Quick Method)

GitLab provides a direct URL in the push output. Copy and paste it into your browser.

Via GitLab Web Interface (Manual Method)

Navigate to Your Project

Go to EBRAINS UI Ecosystem

Open Merge Requests

Click “Merge Requests” in the left sidebar, then “New merge request” (top right).

Select Branches

  • Source branch: feature/handbook/add-search-content (your branch)
  • Target branch: main (the main branch)
  • Click “Compare branches and continue”

Fill in the Details

Title: Make it descriptive.
Description: Click “Choose a template” and select “Merge Request”.

Assign Reviewers

On the right side, click “Assignee” and select a maintainer or team member to review your merge request.

Submit

Review your changes preview at the bottom, then click “Create merge request”.

11. Respond to Review Feedback

A maintainer will review your merge request. They might:

  • Approve it - Great! Your changes will be merged.
  • Leave comments - They might ask questions or suggest improvements.
  • Request changes - You’ll need to make updates.

12. Celebrate Your First Merge!

Once approved, a maintainer will merge your contribution. Congratulations! You’ve successfully:

  • Set up Git and SSH keys
  • Cloned an EBRAINS repository
  • Created a feature branch
  • Made changes and committed them properly
  • Pushed to GitLab
  • Created and navigated a merge request
  • Contributed to EBRAINS!
Edit this page on GitLab ↗