GIT LIKE YOU MEAN IT.

These are not the best practices.

 

These are only practices that have worked for me.

 

Your mileage may vary. 

What should be in a repository?

Two schools of thought: 

 

• LARGE & IN CHARGE: Repos should be large, and share a common tool chain, so that all engineers, regardless of their role, become familiar with the environment. (Not my view.)
   
• SMALL & SEXY: Repos should be small and atomic, so that engineers only make changes to the part of the system that concerns them. Certainly, integrated systems need to be tested together, but loosely coupled repositories make it much easier to make changes that improve performance or add features.  (I prefer this view.) 

Cloning is NOT Check-out

Cloning creates a *copy* of the code onto the hard drive of the programmer.  Similarly "git push" *copies* code from the hard drive to the online repository.  

 

Two programmers can work on the same code at the same time on different clones.  (This is good.) 

Branches Are Your Friends.

Before making any changes to the code, branch the code.  This way, you can make changes in isolation, test, and only when you are done, make a pull request to merge your changes into the main branch.  

Not every branch is destined for greatness.

Most branches that you make will eventually be deleted, as you work on different possible solutions to the code.  You may need to create a new branch to work on a different part of the problem, or when one method of solving the problem seems "stuck" and you want to try another way of approaching it.  This is OK. 

You're not done till it's got coverage

Your code isn't complete - and no pull request should ever be accepted, without adequate test coverage.  

Not even during crunch time.  If you don't have time to write the code and the tests - downscope till you do.  

Software quality is inflexible and cannot be compromised on. 

Test While Driven Development

If you *can* write the tests before you write the code, do it. But sometimes that's not possible (or far more difficult than it's worth.)  Instead, test-while-driven - if you add a new bit of code, make sure you write the test while it's still fresh in memory.  That'll be fine.  

WHY?

Git-based tools, such as Travis-CI, rely on full test coverage to reduce bugs.

The Git Lifecycle: CODING

1. Clone the repository.
2. Create a new (dev) branch for whatever problem you are trying to solve.
3. Commit early, commit often.  (Like saving in a Bethesda game.) 
4. Whenever you wish to save your work but try a new approach, create a new branch.  
5. You will eventually have a branch with a solution, ready for incorporation.  Create a copy of this branch with the following naming convention: 
6. [JIRA issue]-[description]-[coder's initials]
   
   Examples:
   "BI-2115-feature_cachewarmer-bb",
   "BI-2000-bug_printer_catches_fire-mh"

(an aside: Types of Branches)

• EXPERIMENTAL
  While working on a solution, you will create many experimental branches while you try to take different approaches to solving the problem. Most experimental branches will eventually be deleted.
• REVIEWABLE
  While you might not be ready to create a pull request, reviewable branches are in a coherent enough state that you can share them with another developer, and they should be able to understand what's going on. 
• LEGACY/REFACTOR
  Sometimes you might need separate branches to separate legacy code from your new refactored code, because you must maintain the old codebase as you move to a newer technology, framework, etc.  

The Git Lifecycle: Rebasing

1. Switch from your solution branch to the main branch (whether that's "master" or "development").  
2. Pull down the latest changes to the main branch from the online repo. (Other devs may have made changes, and you want to incorporate them.) 
3. Switch back to your solution branch.  
4. Rebase your solution based on the main branch, so that your solution also incorporates any changes made to the main branch.  
5. Fix any merge conflicts, and ensure all tests still pass.  If need be, make manual verification. 
6. Submit a pull request from your solution branch. 

The Git Lifecycle: Pull REquest

If your pull request cannot be automatically merged, go back and rebase your code again.  Pull requests with merge conflicts should be automatically denied. 

 

1. Include the purpose of the pull request. Be clear and specific. 
2. Remember that anyone in the company could be reading the pull request, so the content and tone may inform people other than those taking part, now or later. 
3. Be explicit about what type of feedback you want. 
4. If possible, include a screenshot (so that we can visually see what you are referring to.) 

The Git Lifecycle: Code Review

Get your code reviewed.  You can't catch the bugs you've made - if you could, you wouldn't have made them.

For this reason, no one who makes the pull request can approve the pull request.  

Code reviews may seem painful, but often they can point out a more efficient way to do something, and they can help both the reviewer and the reviewee learn from each other's code, making them better programmers.  

You may wish to refactor based on feedback from the code review, even after the pull request is accepted.  Keep those notes handy!  

TL;DR:

• Clone the repo.
• Branch. 
• commit early, commit often.
• write your tests as you go.
• switch back to the main, pull down any changes.
• rebase your branch based on main. 
• submit pull request. 
• get the code reviewed. 
• pat yourself on back for a job well done.