Project workflow

Do you want to set up a new repository, but you don’t know how to do that? This page is made for you!

Here we’ll explain how we usually create and manage a project using GitLab and PyCharm.

Note: these instructions are suitable for users of multiple IDEs, not only PyCharm. The (few) lines involving PyCharm surely have a correspondence in other IDEs.

Open a new repository

To open a new repository, you have to ask a GitLab Owner. In fact, even if your “New project” button is available, you may not have the permissions to create the master branch, which is needed to initialize your repo.

You’ll find the list of all members and roles at this link.

Ping an Owner, tell him/her which name you chose for your project and… wait until the project has been created.

Connect local machine to remote repo

Now that you have a remote place to save your code, you need to connect your local machine to it. So, open your brand new project on GitLab, click on the blue button Clone… at the top right of the page and copy the SSH link.

Now open PyCharm, click on menu bar VCS -> Git -> Clone… and paste that link. Pycharm will invisibly run git clone ... and will open your empty repo.

Start coding

Your repository is now open on the master branch. This branch contains the production code (for an empty repo, just a Readme.md file) so it is protected to avoid unintentional overwriting. This means that you cannot write directly on it, but you have to create a new branch.

At the bottom right of PyCharm window you should see Git: master: click on it, then click on New Branch. Please fill branch name with the structure <keyword>/<what-is-this-branch-for>, using one of the following keywords:

  • feature: for each new feature you’re writing. It applies to most branches.

  • bugfix, or hotfix: if your branch is fixing a bug you’ve found in master code

  • model: to create a separate model from the master one that needs to be tested at the same time. Used only in (some) Data Science projects.

Now create a new file, add it to Git and… start coding!

Versioning your code

Once you’ve written something that is standalone, we encourage you to save it in GitLab. It doesn’t matter if they are just a few lines: it took you enough thoughts and time, so save it!

To save a file in GitLab, you have to commit your changes. Click on the green tick at the top right of PyCharm window to open the commit dialog window. Review the changes comparing the older version of your file (maybe empty) with the current one, then write a commit message and click commit.

You just saved a version of your code in Git, but it still relies on your local machine. To send this version to remote GitLab repository, you have to push your commit. On the menu bar at the top of the window click on VCS -> Git -> Push…: you’ll see a dialog window with all the commit that are only local, then click push to send them to the remote repository.

Shortcut: if you want to push right after every commit, click on the arrow near commit button in the commit dialog window, then click on commit and push. The push window will appear automatically.

Open a Merge Request (MR)

After many commits the purpose of your branch has been reached: you believe your code is stable and good enough to be included in production. You now want to merge your branch into master.

Open your project on GitLab, then click Merge requests on the left side bar and New merge request. You have to choose the source branch (yours) and the target branch (master), then Compare branches and continue.

As default, Title will be filled with the branch name, but you can change it to a more verbose explanation. Start your title with WIP: if your code is still Work In Progress, but you want a colleague to have a glance of your changes. The WIP status prevent MR from being merged before it’s ready.

It’s a good idea to write a few lines in the Description field, to help the reviewer(s) to understand the purpose of your changes. You can also link:

  • issues: type # and its number. Useful to automatically close related issues at merge, writing Close #issue_number;

  • other MR: type ! and its number. Useful to link other MR which yours is based on.

Assign your MR to the people you want to see it first. They can be reviewers (one or many) or even you, in case MR is in WIP and you need to finish something before review.

Of course, you’d like somebody to approve your job: it’s such a satisfaction! So, set an approval rule, listing how many approvals are needed to merge (usually one it’s fine) and which people can approve this MR. For example, your Project Manager or a colleague with expertise in your programming language can be good choices.

Finally, we suggest to mark the two checkboxes:

  • Delete source branch when merge: to keep the repo clean from unused branches;

  • Squash commits when merge: to mantain master history readable.

Now, submit your Merge Request and wait for things to happen!

Code review

GitLab will provide a useful page in which your code is automatically compared with master branch to enlight differences.

Now, MR assigner(s) will read all these changes in order to check if:

  • code grammar is correct and efficient;

  • your code really does what it should, as described in MR description.

While reading, an assigner may notice an error or something to discuss about. Then (s)he will comment your code, starting a thread. These threads will appear not only in the Changes tab, but also in the Overview tab of MR page.

Usually, code reviews contain many comments, especially the first ones. So, don’t be afraid of them or lower your self esteem just because your reviewer wrote many (many!) comments: take the MR as an opportunity to learn how to code. Trust us: it works!

Once your reviewer has finished reading (and commenting), (s)he will assign you the MR. Now it’s your turn: read all the threads in the discussion and act! You may:

  • change your code in PyCharm, then commit and push;

  • answer to a particular comment, asking clarification or writing that you don’t agree. In this case, always motivate your opinion.

Do not resolve the threads you faced up: resolving is a task of the opener. If you wish to distinguish comments that you went through, let a :thumbsup: or toggle them (toggling is not resistant to page reloading).

At the end of your review, assign again your MR to the reviewer(s). They will read your answers and new changes, checking if you acted appropriately to each comment. If your reaction (answer or code change) satisfies comment purpose, each opener will resolve his/her thread. Differently, reviewer(s) will re-assign you the MR, with new comments where needed.

This MR process works like a ping-pong match, until your code encounters reviewer(s) expectations and it’s merged into master.

Sometimes, instead, it may happen that an MR is closed without merging. This is mainly due to changes in project strategy or to knotty code. Don’t worry if it happens to you: also GitLab developers close MR!

After merging

And now? Open PyCharm and switch to master branch clicking on the bottom right of the window: Git: ``<your-merged-branch-name>`` -> Local branches / ``master`` -> Checkout. Local master will be loaded.

Pay attention: this master does not contain your MR changes. To download them, click on the blue arrow on the top right of your PyCharm window (Update Project), leave the selection as the default and click OK. Now your local master (and all the project) is up-to-date.

Don’t forget to remove your old local branch clicking: Git: ``master`` -> Local branches / ``<your-merged-branch-name>`` -> Delete.

Well, now that you’ve merged your first MR, create a new branch and… start coding for the second one!