Introduction to the Hashmap software development flow and a simple PM-level glossary of terms

hashmap-codeDevFlow.md

Hashmap Software Development Flow

This document explains the general workflow used at Hashmap for software projects on github.

Please feel free to reach out if you'd like me to change any of this.

Github Terms

First, let's discuss some git / github terms that are often confusing.

• git -> a version control software. This software is what allows developers on different machines to collaborate on the same code base in a really efficient way.
• github -> github is a website that hosts git repositories. It has a ton of social / communication / PM features that make it a nice way to collaborate on software projects.
• repository -> this is the collective term for all branches and commits in git. A git repository is the same thing as a project. In general, 1 project = 1 git repository (this can change sometimes).
• commit -> a commit is how code changes are logically added back to a branch. This allows changes to be gradually introduced to the code base along with metadata, such as the author, time, and any messages describing the commit.
• branch -> in a repository, different tracks of work are organized in "branches". The main branch is often called "master", and that is where approved code goes. New branches are created off of master to develop work in progress. When the work in progress is finished, a Pull Request is generated to add this branch back to master as accepted code.
• master -> master is the name of the main, official branch of a repository.
• push -> this is a git command that sends local commits to the central repository on github
• pull -> this is a git command that brings down changes from the central repository to the local environment
• merge -> merging is the process of combining the changes from one branch into another. Most often, we will "merge" the changes done on a feature branch onto master through a PR acceptance.
• PR -> PR = Pull Request
• pull request -> a pull request is a formal process done when the changes in a feature branch are being requested to merge with the master branch. A developer will submit a PR when their feature branch is finished so that someone can review their PR and automated testing / style checking can be done. If the PR is of proper quality, another dev / PM will "accept" the PR and the changes are merged into the "master" branch.

For more details on these terms, click here.

Workflow

Once you have a good understanding of the terms above, our workflow is really simple.

All projects will have a Github repo and a Waffle board. We use waffle.io as a project management tool on top of github.

All new work will be added as "cards" into waffle, which automatically generate github issues on the project repository. These cards will be assigned to developers and scoped to a sprint.

A new developer will follow this pattern on all cards:

1. Clone the repository / pull the latest changes from master (or dev if you're on a more formal project).
2. Find the issue number of you're card and create a new branch off of master named <repo name>-<issue number>. So if you're working on a repository called coolRepository and you're working on issue number 12, the branch name would be coolRepository-12.

• The git command to create this branch is git checkout -b coolRepository-12.

3. Work on your issue by developing code and making frequent commits to your branch with descriptive messages.

• for example, if you add a new API endpoint, you'd commit with git commit -am "new api endpoint added"

4. Push your commit to the github central repository after every commmit.

• this command would be git push origin coolRepository-12

5. When your feature is finished, do a final pull from master and a final commit / push to your dev branch. This ensures that you have no merge issues on your branch.
6. Go to your repository on the github website and got to the Pull Requests tab. Create a new PR from here from your current branch to the master.
7. In your PR, explain what changes you made in your branch. At the bottom of the description, write:

• This PR connects to #<your issue number> -> this allows waffle to link this PR to the issue card on the board.

8. Add a reviewer to your PR who can confirm that your changes are fine and merge your branch into master
9. Once the changes have been merged, checkout your master branch (git checkout master), pull the latest changes (git pull), then delete your local branch (git branch -d <your branch name>).
10. Repeat the process for your next card.