memgraph/docs/dev/workflow.md

Memgraph Workflow

This chapter describes the usual workflow for working on Memgraph.

Git

Memgraph uses git for source version control. If you obtained the source, you probably already have it installed. Before you can track new changes, you need to setup some basic information.

First, tell git your name:

git config --global user.name "FirstName LastName"

Then, set your Memgraph email:

git config --global user.email "my.email@memgraph.com"

Finally, make git aware of your favourite editor:

git config --global core.editor "vim"

Phabricator

All of the code in Memgraph needs to go through code review before it can be accepted in the codebase. This is done through Phabricator. The command line tool for interfacing with Phabricator is arcanist. You should already have it installed if you followed the steps in Quick Start.

The only required setup is to go in the root of Memgraph's project and run:

arc install-certificate

Working on Your Feature Branch

Git has a concept of source code branches. The master branch contains all of the changes which were reviewed and accepted in Memgraph's code base. The master branch is selected by default.

Creating a Branch

When working on a new feature or fixing a bug, you should create a new branch out of the master branch. For example, let's say you are adding static type checking to the query language compiler. You would create a branch called mg_query_static_typing with the following command:

git branch mg_query_static_typing

To switch to that branch, type:

git checkout mg_query_static_typing

Since doing these two steps will happen often, you can use a shortcut command:

git checkout -b mg_query_static_typing

Note that a branch is created from the currently selected branch. So, if you wish to create another branch from master you need to switch to master first.

The usual convention for naming your branches is mg_<feature_name>, you may switch underscores ('_') for hyphens ('-').

Do take care not to mix the case of your branch names! Certain operating systems (like Windows) don't distinguish the casing in git branches. This may cause hard to track down issues when trying to switch branches. Therefore, you should always name your branches with lowercase letters.

Making and Committing Changes

When you have a branch for your new addition, you can now actually start implementing it. After some amount of time, you may have created new files, modified others and maybe even deleted unused files. You need to tell git to track those changes. This is accomplished with git add and git rm commands.

git add path-to-new-file path-to-modified-file
git rm path-to-deleted-file

To check that everything is correctly tracked, you may use the git status command. It will also print the name of the currently selected branch.

If everything seems OK, you should commit these changes to git.

git commit

You will be presented with an editor where you need to type the commit message. Writing a good commit message is an art in itself. You should take a look at the links below. We try to follow these conventions as much as possible.

• How to Write a Git Commit Message
• A Note About Git Commit Messages
• stopwritingramblingcommitmessages

Sending Changes on a Review

After finishing your work on your feature branch, you will want to send it on code review. This is done through Arcanist. To do that, run the following command:

arc diff

You will, once again, be presented with an editor where you need to describe your whole work. arc will by default fill that description with your commit messages. The title and summary of your work should also follow the conventions of git messages as described above. If you followed the guidelines, the message filled by arc should be fine.

In addition to the message, you need to fill the Reviewers: line with usernames of people who should do the code review.

You changes will be visible on Phabricator as a so called "diff". You can find the default view of active diffs here

Updating Changes Based on Review

When you get comments in the code review, you will want to make additional modifications to your work. The same workflow as before applies: Making and Committing Changes

After making those changes, send them back on code review:

arc diff

Updating From New Master

Let's say that, while you were working, someone else added some new features to the codebase that you would like to use in your current work. To obtain those changes you should update your master branch:

git checkout master
git pull origin master

Now, these changes are on master, but you want them in your local branch. To do that, use git rebase:

git checkout mg_query_static_typing
git rebase master

During git rebase, you may get reports that some files have conflicting changes. If you need help resolving them, don't be afraid to ask around! After you've resolved them, mark them as done with git add command. You may then continue with git rebase --continue.

After the git rebase is done, you will now have new changes from master on your feature branch as if you just created and started working on that branch. You may continue with the usual workflow of Making and Committing Changes and Sending Changes on a Review.

Sending Your Changes on Master Branch

When your changes pass the code review, you are ready to integrate them in the master branch. To do that, run the following command:

arc land

Arcanist will take care of obtaining the latest changes from master and merging your changes on top. If the land was successful, Arcanist will delete your local branch and you will be back on master. Continuing from the examples above, the deleted branch would be mg_query_static_typing.

This marks the completion of your changes, and you are ready to work on something else.

Note For People Familiar With Git

Since Arcanist takes care of merging your git commits and pushing them on master, you should never have to call git merge and git push. If you find yourself typing those commands, check that you are doing the right thing. The most common mistake is to use git merge instead of git rebase for the case described in Updating From New Master.