Code Contributions - Amaury Yacksmith

module-name: "code-contributions"
area: "Product Knowledge"
gitlab-group: "Create:Editor"
maintainers:
  - [cynthia]
  - [rvzon]

Overview

Goal: You feel proficient at making a code merge request to the GitLab project.

Objectives: At the end of this module, you should be able to:

  • open a merge request specifically for a code contribution.
  • test your code locally.
  • follow the contribution process.

Stage 0: Create Your Module

  1. Create an issue using this template by making the Issue Title: Code Contributions -

  2. Add yourself and your trainer as the assignees.

  3. Set milestones, if applicable, and a due date to help motivate yourself!

  4. Update support-team.yaml to indicate that you're ready to work on tickets in this knowledge area:

    knowledge_areas:
- name: Code Contributions
  level: 2

Stage 1: Getting to your first MR

The guidelines and workflow:

  1. Take a look at our development guidelines. For now, stick with the main page and the table of contents to get a sense of what is included.
  2. Start with reading the Merge request workflow, with special attention to the commit message guidelines.

Getting changes done:

  1. Get your GitLab Development Kit (GDK) running. If you have any issues, post in the #gdk Slack channel for help.
    • Alternatively, if you do not need to connect your GDK to any integrations (runner, cluster, auth), you can use GitPod.
  2. Choose something to work on. Link the issue or related ticket:
    • For your first MR, we recommend choosing something simple that would not involve spec files, database migrations, etc. unless you're experienced in those areas.
    • If you don't have anything ready, some possibilities include:
  3. While the merge request workflow says to fork the project, you can instead go into the /gitlab directly inside your GDK repo and create a feature branch.
  4. After you've made the code changes, make sure to preview it using your GDK.
  5. Make sure you have lefthook installed. It will run the tests you need before you push, and take a read over the configuration to understand what it checks.
    • The style guides page also covers how to run the tests individually. Typically, you want to run danger, and RuboCop.
  6. Read over when and how to make a changelog entry. If your MR requires a changelog, amend your commit to include the Changelog trailer.

Getting your first merge request in:

  1. When you're ready, push your changes.
  2. When creating the merge request, fill in as much of the template information as you can. Some of these you can fill in later instead of at creation time.
    1. Link to the issue and/or ticket:
      • If there is an existing issue, assign yourself to the issue and add the label ~"workflow:in dev". You can also use the /copy_metadata #123 quick action to copy labels, milestone, etc.
    2. Labels: add appropriate labels including relevant support team labels.
    3. Milestone: Next release number (or the one after if you don't think it'll be merged by the next one's due date).
  3. Read over the Code Review Guidelines paying special attention to getting and assigning your MR for review.
  4. Preview your change using the review app.
  5. Once your MR is merged, you will want to test it on:
    1. staging. Use the Google Login to create an account if needed.

Stage 2: Review other contributions

  1. Review 5 of these previous code contributions from Support team members to get an idea of the variety of code contributions, and a better sense of the process. It's also a good idea to check the previous commits of the files you wish to change. You might find a previous commit that is similar to what you'd like to implement. Note: If you find better examples, feel free to edit this list.
    1. Simple view change: Display Group SAML provider ID and group path with link
    2. Simple rake task: Support multiple mailboxes incoming email check
    3. Simple bug fix with spec changes: Add handling for Integer types when logging API parameters
    4. Simple db performance (N+1) example with specs: Looking up solo_owned_groups for a user N+1
    5. Adding to helper files: Add RHEL 8 to helper and SELinux files
    6. Bug fix with multiple specs: Correct the permission according to docs
    7. Bug fix with multiple controllers and specs: Fixing count on Milestones
    8. Adding rake task involving concerns and spec: Rake task to verify secrets using gitlab:doctor:secrets
    9. More complex example: Add SELinux module for gitlab-shell
    10. More complex example involving improving query performance, with feature flags and specs: Allow secondary emails when searching user emails, with feature flag rollout issue and follow-up MR to remove feature flag
    11. Adding new API endpoint that went through multiple iterations and AppSec: Add PATCH /users/:id/disable_two_factor endpoint
    12. Bug fix for a wildcard redirect in GitLab Pages: Don't redirect acme challenge
    13. Simple logic update in the UI: Correct the logic on duplicate package toggles
    14. Simple update to rename a label: Renaming the rules label to conditions
    15. More complex bug fix to allow project transfers from one namespace to another after removing NPM packages: Fail TransferService only if there are namespaced npm packages

Stage 3: Contribute!

Beyond the very basics, you may make changes that touch spec files, the database, or other parts of the codebase. Some additional reading:

  1. If it's a significant feature or improvement change, you will want to put it behind a feature flag. Take a look at when and how to use a FF.
  2. Read over the testing best practices with focus on RSpec.
  3. If your changes require database changes, you will need to review the database development guidelines.

Keep in mind that while this module specifically covers the GitLab project, the process is generally the same for all projects in gitlab-org, so you can link to work done in other projects. Some of the other projects can have additional development/testing requirements or guidelines, so it's recommended to read through the relevant README.

  1. Link 2 submitted merge requests:
    1.   gitlab-org/omnibus-gitlab!7164 (closed)
    2. __

Penultimate Stage: Review

You feel that you can now do all of the objectives:

  • open a merge request specifically for a code contribution.
  • test your code locally.
  • follow the contribution process.

Any updates or improvements needed? If there are any dead links, out of date or inaccurate content, missing content whether in this module or in other documentation, list it below as tasks for yourself! Once ready, have a maintainer or manager review.

Final Stage: Completion

  1. Have your trainer review this issue. If you do not have a trainer, ask a support code contributor to review.
  2. Manager: schedule a call (or integrate into 1:1) to review how the module went.
  3. Submit a MR to update modules and knowledge_areas in the Support Team yaml file with this training module's topic. You will now be listed as an expert in this topic on Skills by Person page.
  4. Consider also taking the Documentation training which focuses on GitLab docs changes.
Edited by Amaury Yacksmith