As I am graduating this coming June 2016 (yes - I am looking for full time careers in the California area), all engineering students at Drexel University do what is called a senior design project. My group includes a MS/BS Computer Engineering student Hardip Sahota, a BS in Computer Engineering student Steve Wetzel, the amazing ECE professor James Shackleford, and myself. The name of the project is Groupthink, and we are working on combining algorithmic trading strategies with social media emotional sentiment using IBM Watson and data from StockTwits.
Working in group development projects can generally be confusing. Not defining a clear development workflow in the beginning will quickly devolve the project into an organizational nightmare. Adopting the development workflow I learned while working at Beta Software Technology lead by our Chief Architect Allan Simon, I wrote a brief guideline for how all four people in the senior design group should work together through Github.
This Github Style Guide will cover:
Synchronizing our master branches
How to break large tasks into sub-tasks
Creating the Github Issue using its Issue Tracker
Creating the branch and branch name convention
Frequency of commits
How to name our commits
Issue pull requests
Unless you want to have your spleen removed with a rusty spoon and be the next human sacrifice to Professor Gerber, you will not push directly to master. You have the permissions to because of Github, but we will not be doing that!
1. Important: Synchronizing Branches
Slack will tell you whenever a branch has been merged.
However, to ensure we are all developing in the latest master, we should perform a
git pull origin master prior to creating a new feature branch.
2. Breaking large tasks to sub-tasks
Before any code is written, we should ask ourselves, how much of a particular task, for example, writing the EOD stock data parser, can be broken apart into sub tasks.
- Develop the class that reads the stock/futures indices from the MySQL database to determine which indices we will be parsing and persisting
- Develop the class that gets data from quandl given a futures/stock index and saves it into a data structure
- Persist the data to the database
In this main task of creating the parser and persister, it could be divided into three subtasks. Now that we have a higher level understanding of how tasks could be separated into (note - you don't have to follow my sub-tasks), we can create the Github issue.
3. Create the Github Issue
Not only will we be using Trello to track development of tasks, we will also use Github's Issues tracker to determine our branch names and track the actual code development.
- Create a new issue on Github
- The title should provide a brief higher level explanation of what you want to achieve, for example, "develop the class that reads the stock/futures indices from the MySQL database to determine which indices we will be parsing and persisting"
- Description can be left blank
We're almost able to start developing now.
4. Create the Branch
Within your command-line utility (or GUI), you can create your branch. The style guide is as follows for your branch name. We will be using the underscore notation to separate words.
git checkout -b [task #][short_title_using_underscore_notation]
So in this specific case, the task # from the Github issue is
2, we can use the following command:
git checkout -b 2_demonstrating_pr
5. Commit Frequency
Unless the task is small (like 1 - 2 lines of code), you should periodically commit, for not only ensuring your code is saved, but so:
- You can rollback to a previous [or more] commit in case anything fails
- Provide a chronological overview for yourself as well as your teammates of what you've done
6. Commit Style Guide
The commit messages for during-task-development should have the keyword
task #[number] or
close #[number]prior to the message.
This allows Github to assign your Github issue TO your commit message, like:
It's a really useful feature, and allows anyone to look at our project's commit logs to determine which commit corresponds to which issue on the web interface.
During task development
You use the following commit message with the
task #[number] format during the development of your task.
git commit -m "task #[task #]: [a brief description of what you've done]"
git commit -m "task #1: updated API URL for quandl parser"
Final commit of task development
You use the following commit message with the
close #[number] format during at the final commit of your task development. The
close keyword will physically close your issue on the Github Issues page, marking it as completed and closed.
git commit -m "close #[task #]: [a brief description of what you've done]"
git commit -m "close #1: fixed off-by-one index error"
7. Issue Pull Request
Issuing a pull request will allow us to review the changes and merge the task branch back to master. Remember - we will never push directly to master.
- Create a pull request in the home page of the Groupthink repository
- Open the pull request
- After this step, the person in charge of the PRs will be able to review the changes, and merge through the web interface or through the command-line.
Do you have suggestions on how to make it better? What development workflow do you use when working with multiple people?
Drop your thoughts in the comments section!