Developer Guide

Intro Github Guide: How to Develop QuEmb on Github:

After cloning the code on your local computer, you are ready to develop!

First, some key terms:

• local repository refers to the version of the code you have downloaded on your computer. These changes are only saved locally.
• remote repository refers to the version of the code up on Github.
• main is the master branch of our code. This is the working, reliable version with the well-tested features
• feature_branches are the in-progress branches which are home to changes that you and others make. Everytime you want to change or add something to the code, make a new branch! These are deleted when your changes are finished and merged back with the main branch.
• issues are raised when you run into a problem. Try to be as specific as possible when logging any problems you see!
• and more... (rebase, diff, stash, tags/versions, linters, and more...)

Some tips to using Git locally on your computer to navigate the code:

What's your local Git status?

When in the directory of your clone, to see the status of your branch of code (i.e. have you made changes to the code?), use:

git status

To see what branch of the code you are on, use:

git branch

How to keep your local Git updated with the remote repo?

To keep your local Git of the QuEmb software up-to-date with the remote version, use:

git fetch <remote>

In most cases, this is simply origin, the remote code location. This will not update your local code, but it will download all of the changes and commits locally for you to review. You can fetch a specific branch, using:

git fetch <remote> <branch>

You can then merge the fetched code (now located locally, at origin/<branch> rather than origin <branch>) using:

git merge origin/<branch>

This will change your local code so that it matches the fetched remote version. To keep your local version of the code up-to-date with the remote version (i.e. keep updating the code to include commits from other work and contributors which have been pushed to the main branch), use:

git pull origin <remote>

This will fetch and merge any changes into your local code, together in one step. If you have your local branch tracking the remote one, you can simply use git pull instead.

How to manage new branches?

If you want to make a new branch, or if you have made changes locally and want to make them a new branch, use:

git checkout -b <new_feature_branch>

This will save any of those changes, at your current code progress point, on a new local branch (i.e. not on the remote repo, but locally on your computer). You can switch branches, once your changes are stashed or saved to a different branch, simply using:

git checkout <diff_feature_branch>

These changes all happen with your local code version, not changes to the remote repo. To add the new branch to the remote repo, and set up tracking between your local branch and the new remote one, use:

git push -u origin <feature_branch>

How to start making changes to the remote repo?

When you make changes to a given branch of the code, you need to commit those changes to keep a log of any progress, saving changes in the local repo. Any files that you are committing must first be staged, by telling git which files go in the commit. You can see which files were marked for your commit using 'git status'.

git add <file> stages a code (as-is! not any later changes you make to the file) to be committed, while git rm <file> un-stages it.

You can stage the whole code for a commit simply using git add . at the head of the directory. You then can commit your staged changes using:

git commit -m "<your message here>"

where the -m flag lets you leave a message (which we encourage!). If you do not need to be as careful in your staging (i.e. you would like to commit all changes), you can use:

git commit -am "<your message here>"

Note that you will need to add any new files you added to the branch, with git add <new_file>, when doing this.

After committing any changes, you will have to make sure your local branch with its changes can be successfully pushed and merged into the remote one. You should have been periodically pulling from the remote repo to make sure the branches "agree" and are as up-to-date as possible.

Some helpful tips if they do not agree and how to pull from origin: (from someone else:) )

To save and share your changes on the remote repo, push them to their corresponding remote branch:

git push origin <feature_branch>

This will push all of the commits and their logs to the remote feature branch saved on Github in the remote repository. These will merge with the remote branch. This can sometimes be merged automatically, but other times will require you to go through by hand. (some advice for this?)

Once you have made all of changes you see fit, tested them (using the different checks below), and would like to add them to the main branch of the code, make a pull request on Github to merge your feature branch with the main one. You should describe the changes made in the request, including addressing any issues that you have fixed with your changes. You can assign reviewer(s) to go through and approve the request before the code can be merged into the main branch and the branch is deleted. As configured, QuEmb requires a reviewer to approve PRs before they can be merged to protect the main branch.

How to stay synchronized with main

If you branched off from main and while doing your changes someone successfully merged their code into main via a pull request then you have to incorporate these changes into your code.

Assuming you are in your feauture_branch and want to synchronize it, the recommended way is

git pull origin main

which pulls from the remote (origin) and merges into your feature_branch.¹

---

¹ If you know git and know what you are doing you can also do a git rebase. Note that we anyway squash commits, so the history of main will be linear.

Pre-commit Hook

Run

git config --local core.hooksPath .githooks/

in your local quemb git directory to activate the pre-commit hook.