Month: December 2018

Always squash before opening Pull requests

When you are working on a feature it makes sense to make incremental commits as you proceed with the work. Then when you are done you want to just open a Pull Request and wait for approvals. But it is important to squash your commits into a single commit before merging  into the master branch. The reason is if you need to revert your code change, you can revert a single commit and move on. You don’t want to be in a position where you have a serious bug in production, and you are trying to figure out if you reverted all of the commits. Save yourself the panic and trouble by squashing before you commit to your master branch. Some services like github will automatically squash for you, use that feature if you have it. 

Useful git commands for squashing

# git --amend amends your last git commit 
git commit --amend

# rebase is the command used to actually squash commits 

# git rebase -i HEAD~4 rebases the last 4 commits including the head commit
# the -i toggles interactive mode which opens an editor
git rebase -i HEAD~4

When you run the command git will open a text editor that asks you to choose what to do with each commit.

Example screen when you start an interactive rebase. All commits are picked by default.

The default is the vi or vim editor. In this window you want to change the command for the commits you want to squash. 

Interactive rebase menu

Then the next window will give you a chance to modify the commit message for your new combined commits.

Update the commit message for the squashed commits
Final commit after rebase

Design Documents for Distributed Companies

How do you hash out architecture and design at a remote only company? Slack chats and phone calls are a slow way to communicate with an entire team. And miscommunication with people 1000s of miles away can cost you the time and money you were hoping to save by working remotely. 

The Design Document workflow

Some companies have a design document centric workflow. At the beginning of a project instead of writing Jira tickets or tasking out stories, an engineer will spend some time writing a 3-10 page document which describe the plan of attack for the project. This doc will include assumptions, design decisions and constraints, as well as a summary of the changes to be made. The document is not an exhaustive specification, but can include proposed interface or library changes. Then the team will have a review session to read and ask questions about the design. Next after some revisions, and possibly a follow up session, development will begin. 

Google Docs or any other shared document tool is sufficient to support the document review process. If you want to make the process truly asynchronous you could rely only on document comments and skip the meeting all together. 

Typically, a design document should be required both embarking on any significant project or feature addition. Adding a new button to a web form would not need a document, but building a new web service or adding a major feature would. 

When I worked in a distributed consulting company we used this workflow for proposals and Level of Effort estimates. But software design was usually handled by discussion and whiteboarding followed by implementation with half-hearted documentation occurring at the end of the project. A design document process would have helped share design between the east and west coasts keeping more of our projects on the same page.