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"

Github

All of the code in Memgraph needs to go through code review before it can be accepted in the codebase. This is done through Github. You should already have it installed if you followed the steps in Quick Start.

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:

# TODO(gitbuda): Discuss the naming conventions.
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 by pushing the branch to Github and creating a pull request. You can find all PRs here.

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.