
Author:	Syed Ali
Last Checked By:	Syed Ali
Last modified By:	Petri Peltomaa
Status:	In progress
Last Updated:	23.9.2025
Version:	1.1

Best Practices for Making Changes in Your Code#

Congrats! You forked a repository and want to work on the codebase and maybe improve existing code or fix bugs. You could hypothetically change the code right away but it will be very cluttered, can mess up things, it can break pipelines and whatnot and it's just not good in the long run. So this document is a guide on what the best practices are to make changes in your codebase in Gitlab. As an example, I will be making a fix for a critical vulnerability in the Symfony package.

Steps To Take Before Making Changes (Planning)#

Creating Labels and Issue Boards#

Make sure there are sufficient labels to organize your work so it will be less cluttered and easier to find files or issues in the repository. To create labels, from the sidebar, we will go to manage --> labels and click on new label. Here we create our desired labels some examples could be 'in progress', 'waiting for review' etc. It is good practice to create a short description if the name is not self-explanatory. Labels nav

After creating the labels from the sidebar we will go to Plan --> Issue Boards click on new list, select label, and then select our desired label e.g. 'in progress', and click add to board. The reason for this is so that issues can be easily visualized and it gives us a summary of the backlog, under work, and done issues.

Creating Issues#

As mentioned we are fixing a security vulnerability as an example so I will tailor this guide to it but, this same guide can be implemented for other non-security fixes as well. Now to find the vulnerability we are going to fix, from the sidebar bar go to Secure --> vulnerability report select(click) our issue of password in URL, and then click create issue. issue creation

We will give it an appropriate name, and in the description, we will write some important stuff like the location of said file where the changes will be done; and a proper description of what the issue is and what could be its impact, etc. Then we will assign it to the relevant person in our project. We will give an estimated due date. Lastly, we will select our relevant labels, e.g. 'open' or 'in progress' and then we click on create issue

This Planning should be done for all/most of the issues your group plans to solve. Create issues and assign labels to them Initially the issues that are not being worked on should be in 'open' or in 'backlog'

Managing Issue Boards#

If you have assigned your labels correctly and created your issue boards correctly as well your relevant issues should automatically appear in your issues boards, but if you did not then all issues by default go to the open issues board where you can assign further labels.

Now whenever you want to work on an issue just move it from 'open' to 'in progress' and when it is done move it to 'waiting for review' it's that simple.

Branches#

Now don't rush, there is still one step left before the coding. We create Branches in repositories so we don't mess up other people's progress and vice versa, and it is much neater this way. Navigate to your home page, just below the name of your repository you should see a '+' sign, you will click it and click new branch. You should also give it a proper meaningful name e.g. Vuln - passwd in url - symfony pckg creating branches

Fixing/Changing the code#

Let's Navigate to our issue board and select our relevant issue to work on. If the guide was followed correctly then the issue should have a file location, let's move there. BEFORE making the changes make sure you are in the correct branch by selecting the drop-down menu from the top as shown in the picture.

Now you can make your changes in the code, however you like.

selecting branch

Merge Requests (MR)#

After you have pushed your changes in the code and all of the CI/CD pipelines have passed, you move your issue to waiting for review or your equivalent issue board then you go back to your file where you made the changes and you click a small button on the top that says Create Merge Request creating MR

You give the MR a title and a good description of what changes you made, and how would they affect/reflect in the main branch, if there were problems, if the pipelines passed, etc. Then you assign the MR to your group leader and at least 2 other people other than you, who will go over your code and see if it makes sense. You will give the MR its relevant labels and then click Create Merge Request approving MR

The best practice is that at the end of the week, the team will host a meeting where all of them will be on board, assuming they have reviewed the code, if all assignees agree and everything seems fine, you or the leader will click the Merge button.

Closing the issue#

Finally, after all these steps have been completed you will navigate to issue boards and move the relevant issue to closed so then the issue/fix is finally finished and now you can select a new issue and move on with the project.

p.s. If you made it this far, thanks for reading/referring to my guide, I hope it helped you :)

Guide for CLI commands on using git#

How to make branches in git#

Branches can be made from gitlab website but in this guide we are focusing on the CLI commands. To make a branch run this command git switch -c "branch_name_here".

Test the status with git status to see that you are indeed in the created branch.

Always use git status to see what is going on with the repo and that you are inside the branch you want to be in. It is a good practice to not use git add -A because there might be changes you do not want to have in there for example some programs might modify files without your permission inside the repo.

Let's commit these changes made during the guide with git commit -m "Comments here".

Now to push the changes made during this guide and let's see what happens.

We can see that git is complaining about the repo doesn't have an upstream branch. This happens because the branch created is "living" on local machine and git doesn't know where to actually push it. To fix this we have to use different command git push origin "branch_name" to set the upstream. After using that command we can continue normally with git commit and git push.

Sometimes git push origin "branch_name" command doesn't add tracking to the branch and in future git push command might give the upstream error, we can use "-u" option like this git push -u origin "branch_name" to make sure the branch gets tracking and has correct upstream.

Now git knows the upstream and the branch should be visible in the gitlab web-interface.

Now we can develop the new feature/features etc in this branch without affecting the main branch. Usually when the new feature is done and no work has to be done the feature branch will be deleted, more on that part later in the guide.

Merge requests#

Now that we have made changes, we have commited and pushed them and we are ready to merge the feature branch to the main, we do it by creating a merge request. Go into the gitlab's web-interface and a banner about creating a merge request at the top of the page should be visible.

By clicking that button a new page opens up where we can create the merge request.

Fill out the description as detailed as possible so that the purpose of the merge request is as clear as possible. Give an assignee to assign the merge request to. Fill other fields as required, decide if you want to destroy the branch or not after the merge. (usually the branch is destroyed)

After the merge request is created, new page opens up where we actually merge the repo. Here we can decide if we want to change some settings like "Delete source branch" etc. For the sace of the guide i do not want to destroy the source branch whis is the "guide" branch in this case.

Click the "Merge" button to merge. Now the main branch has the same content as the feature branch has.

Some extra notes on good practice for git commands#

1) Always check status of the repo with git status before git add or git push to make sure you are adding and pushing files you intended to.

2) Try to avoid using git add -A because some files might have changed without you knowing about it.

3) To check what upstream urls the branch has, use the git remote -v command. With this information you know what the origin repo is and that the commits go into a correct repo.

4) Never use git checkout for switching branches, it can destroy the whole branch accidentally. Check out this link -> Differences between git checkout and git switch

5) Always usegit pull before starting to work in any branch, this way we get the changes from the upstream and no one's work will be overwritten.