Getting Started

This guide will help get any new group members started on contributing to the project since diving into a large codebase with unfamilliar tools can be a little daunting. While some of the information only pertains to the Halo-Suit-Beaglebone repo, much of the information here shows many best practices that are used in a lot of projects that are hosted with Git.

Git

We are using git for this project's version control. if you're unfamiliar with the tool I recommend trying this tutorial to get a basic understanding of how it works. Git may seem like a bit much at first but if you learn to use it you will find it to be a power full tool. A final word of advice when it comes to Git is don't try to force commands. When a command fails there is usually a reason for it and it's often something that can be solved by asking one of the group members for help. Many git commands can be forced through using the force flag -f but this is really bad practice since forcing the command may mean that you're forcing the repo to overwrite someone else's hardwork.

Setting up a local repo

The first thing you want to do is to set up your own local repo

$git clone --recursive https://github.com/sfu-embedded-cosplay/halo-suit-beaglebone.git

This will create a folder containing the contents of the repo and all of it's submodules. Before continuing we should set a few options.

$git config user.email "<github email>"
$git config user.name "<github username>"
$git config --global core.editor "<editor>"

The first two lines will set your identity which is used when you create commits. If you only use one git account then you can add a --global flag after the config to set it for all repos on your system, I would be aware of this if you ever have need to use another git account on your system. The last line changes the editor used by git when making a commit message, rebasing, or anything else, this can be set to your favorite editor (vim, emacs, sublime, atom, gedit(really?), g++).

Issues

Github issues are where we keep track of tasks, enhancements, bugs, questions and miscellaneous documentation.it is also the best place to start to looking for work to contribute to. if there is a task that is tagged "help wanted" that means it is a task that currently needs someone to contribute to it. these issues will have a description of the problem, and possibly a checklist and/or some usefull resources. if you decide to do this task self assign your self to it and if it's a small task you can remove the "help wanted" label as well so that people know that the task is being worked on by someone. if you have any questions about that task you can comment in the issue or message the one who posted it. if you have a question or come across a bug while working on the project an issues is a good way to document it. even after an issue has been closed it can still be usefull since it documents any changes that were made and what their rational was. also any solved bugs or answered questions may be relevant to someone else later on and may save them some time.

Branches

When making changes you shouldn't directly make changes to the master branch instead these changes should be in a separate branch. you can check what branch you are on with the command:

$git branch

this will print all branches in the local repo, one of them will have an asterisk next to it which indicates the branch you are currently on. you can switch branches by with:

$git checkout <branch name>

if there is a pre-existing branch in the main repo that is not in the local repo you can retrieve it with:

$git fetch <branch name>

you might be tempted to use $git pull but this command will merge that branch into your master and not pull the branch separately. if the branch hasn't been created you can create one with the commands:

$git branch <branch name>
$git checkout <branch name>

or more simply with:

$git checkout -b <branch name>

Commiting

After making a certain amount of progress in your contribution it's good to commit those changes. First thing to do is to:

$git status

This shows which files you're tracking and which you are not. Next you need to add those files that you made changes to that you want to be committed which can done with:

$git add <file name>

This will add <file name> to the commit. There are a few shortcuts to adding all the files in a folder or all untracked files in the repo but this may add things you don't want to commit and is generally bad form. Once all the files have been added which you can check with $git status you can call:

$git commit

Which will bring you into the editor that you set earlier. Here you need to write a commit message which will explain to others what this commit will do. Basically a commit message should have a short message briefly describing the commit followed after a blank line by a body that explains the commit in greater detail. This is important because it explains in detail what your commit does to the repo before they look at your code changes. A good link on writing good commit messages can be found here. Below is an example of a correctly formatted commit message:

Refactor halosuit.h's constants

Replaces the constants in halosuit.h with an enumerator structure.
This will increase the scalabilty of adding new hardware while
simplifying the structure for accessing the file descriptors for
the GPIO.

When finished writing the message save and quit the editor and the commit should finish. It's good practice to commit often since it will make what you're doing more transparent and as well a making it easier to undo changes if we ever need to rebase in the future. After one or more commits you can sync up your repo with the github repo by doing a push. We only want to push our branch to a branch on the github repo which can be done with:

$git push origin <branch name>

This may require some github authentication and as well as permision to push to the repo. It's important that you don't push code that doesn't compile to the main repo since someone else may be working on the same branch which may cause their code to stop working if they pull your code.

Pull Requests

After verifying your contribution through testing you will want to merge your branch into the master branch, this is done through pull requests. To do this click on the pull request button on the right side of the Github repo page. On the linked page click the create new pull request button which will take you to a page for creating pull request. On this page you will see two tabs labeled base and compare, set the base to master and compare to the branch that you want to merge into master. Next, just like commits add a brief description of the pull request and a more in depth description below. If there are relevant issues that would be closed with this pull request you can write closes #1 or resolves #1 to close that issue when the pull request is closed. After you're done click the create pull request and thats it. Someone else in the project will review the pull request and merge it in.

DON'T merge your own pull request since the whole purpose of merge requests is to have another person look over your changes, since we're all human we can all miss things.

A word on code style

For the most part we use Brian's c style but for naming schemes we use underscores instead of camelcase.

int no_upper_case;
void not_camel_case();

for public functions we put the module name infront of the function name like so:

/*
 * beagleblue.h
 */
 void beagleblue_init();

we can be flexible with variable naming styles as long as they are readable and consistent.

SFU-Embedded-Cosplay / Halo-Suit-BeagleBone

How to contribute to the Halo-Suit-BeagleBone project. #10