Code Contributions - Katrin Leinweber
module-name: "code-contributions"
area: "Product Knowledge"
gitlab-group: "Create:Editor"
maintainers:
- [cat]
- [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
-
Create an issue using this template by making the Issue Title: -
Add yourself and your trainer as the assignees. -
Commit to this by updating your knowledge_areas by updating the Support Team yaml file with this training module's topic. -
Set milestones, if applicable, and a due date to help motivate yourself!
Stage 1: Getting to your first MR
The guidelines and workflow:
-
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. -
Start with reading the Merge request workflow, with special attention to the commit message guidelines.
Getting changes done:
-
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.
-
specifically, QA tests aren't working yet. Asked in #gdk.
-
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:
- removing a manual Rubocop exclusion as explained for this Hackathon (gitlab#239356) and adhering the newly flagged codes to the RuboCop rule,
- issue on updating code based on ruby version or warnings (such as kwarg deprecation warnings),
- resolving a "static code analysis" labelled issue,
- issue or epic on migration components (similar to gitlab&3951),
- consider a Support Priority issue (though these may or may not be good for new contributors),
- ask the team, especially your trainer, a senior, or your manager,
- as a last resort, you can check the "good for new contributors" labelled issues.
-
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. -
After you've made the code changes, make sure to preview it using your GDK. -
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.
-
Read over when and how to make a changelog entry. - If a changelog is required, you will need the MR number. You can follow the steps below to create the merge request, then create the changelog in a further commit, or alternatively, amend your commit with the ID after creating the MR.
Getting your first merge request in:
-
When you're ready, push your changes. -
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. -
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.
- If there is an existing issue, assign yourself to the issue and add the label ~"workflow:in dev". You can also use the
-
Labels: add appropriate labels including relevant support team labels. -
Milestone: Next release number (or the one after if you don't think it'll be merged by the next one's due date).
-
-
Read over the Code Review Guidelines paying special attention to getting and assigning your MR for review. -
Preview your change using the review app. - Once your MR is merged, you will want to test it on:
-
staging. Use the Google Login to create an account if needed.
-
Stage 2: Review other contributions
- Review 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.
Note: If you find better examples, feel free to edit this list.
-
Simple view change: Display Group SAML provider ID and group path with link -
Simple rake task: Support multiple mailboxes incoming email check -
Simple bug fix with spec changes: Add handling for Integer types when logging API parameters -
Simple db performance (N+1) example with specs: Looking up solo_owned_groups for a user N+1 -
Adding to helper files: Add RHEL 8 to helper and SELinux files -
Bug fix with multiple specs: Correct the permission according to docs -
Bug fix with multiple controllers and specs: Fixing count on Milestones -
Adding rake task involving concerns and spec: Rake task to verify secrets using gitlab:doctor:secrets -
More complex example: Add SELinux module for gitlab-shell -
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 -
plus Pipeline quota page: Show projects with most CI... (gitlab-org/gitlab!83680 - merged) about FFs
-
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:
- [-] 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.
-
Read over the testing best practices with focus on RSpec. - [-] 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.
- Link 2 submitted merge requests:
Penultimate Stage: Review
You feel that you can now do all of the objectives:
- copy the list of relevant objectives
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!
-
If you have feedback on whether the issue suggested above for first MRs were suitable or not, please do so in support-team-meta#3084 (closed). -
Update ...
Final Stage: Completion
-
Have your trainer review this issue. If you do not have a trainer, ask a support code contributor to review. -
Manager: schedule a call (or integrate into 1:1) to review how the module went. -
Submit a MR to update the Support Team yaml file with this training module's topic under your list of completed modules
. -
Consider also taking the Documentation training which focuses on GitLab docs changes.