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
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:
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.
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
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.
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 theconfig
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:
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:
if there is a pre-existing branch in the main repo that is not in the local repo you can retrieve it with:
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:or more simply with:
Commiting
After making a certain amount of progress in your contribution it's good to commit those changes. First thing to do is to:
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:
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: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:
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:
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
orresolves #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.
for public functions we put the module name infront of the function name like so:
we can be flexible with variable naming styles as long as they are readable and consistent.