Welcome

git repository best practices

Details
Category: Tips
Published: Thursday, 30 July 2020 23:09
Written by Christopher Carr
Hits: 1661

git is today’s source repository manager of choice for software development professionals, but increasingly it is being misused or abused. Here are some hints to make your git usage more professional and hopefully some reasons as to why.

git is efficient at managing changes in text files, but not so for binaries.

.gitignore

What is it?

The .gitignore file (note the . in the filename) is a reserved file used by git that identifies project files & folders which should not be written into your repository and therefore identifies the remaining subset of files that are necessary to your project.

Files that should not be included in your repository are binary outputs and other generated files from your build process. The .gitignore file should also exclude any other files that do not constitute “source”, for example files containing secrets used in local development.

There are many web resources where you can learn all about the structure of the .gitignore file.

Why use a .gitignore file?

While you can stage selected source files in each commit, who wants the hassle of manually selecting relevant files for each commit? It is both time-consuming and error prone.

If you don’t have a .gitignore file in your repository, you increase the chance that you will include files in your commits that you don’t need (or want) in your git repository.

It should be noted that manually selecting files to stage increases the chance that you will miss something that should be checked in.

Exclude binaries

Binaries in your repository, especially binaries that change, lead to repository bloat because git stores each change to a binary as a complete copy. This is a bad thing since the larger the git repo, the longer it takes for someone to pull it down and start working on it.

NuGet packages are a special type of resource used in dotnet projects. They should never be stored in your repository as they are binary and often quite large. NuGet packages do not change once published, so you can use the command dotnet restore to retrieve the packages for your dotnet project.

Where can I get a .gitignore file?

If you’re using dotnet, you can type dotnet new gitignore to create a dotnet specific .gitignore file in the current folder.

For other project types, GitHub maintains a handy collection of .gitignore templates

https://github.com/github/gitignore

More than one .gitignore file

While it is normal to include a single .gitignore in the root of your repository, you can have as many .gitignore files in your repository as you have folders.

If your repo contains more than one type of project, it is common to have a .gitignore file in the root of each project folder.

readme.md

When you create a new repository, it is good practice to add a readme file in the root of the repository explaining what the repo contains, where it is used and how it is built & deployed. This file acts as the starting point for any new development or collaboration or as a quick-
start on a project that may not have been touched for some time.

A standard git readme uses markdown format (hence the md extension). Markdown supports simple formatting like headings, bullets and lists.

The readme file is an essential part of your application source code, and it should be maintained alongside code changes. In fact, many organisations have a question on Pull Request creation asking you to confirm that you have updated the readme file for this very reason.

You should add a readme.md in the root of each git repository. Of course, if you have several projects in your repository, you can have one readme.md per project in each project folder.

Your readme file should contain the following minimum detail

  • Project title: A one or two paragraph statement explaining what the repo is about
  • Build Status in Continuous Integration (CI)
  • Installation instructions and/or usage example(s)
  • Development setup – required tools, frameworks and how to build the project
  • Test setup – how to run the tests with examples
  • Release History – with changes and bug fixes. Especially good for public repos
  • Credits
  • License

There are several sample readme templates on GitHub that are easily found via google.

Agile and workflow using git

Details
Category: Tips
Published: Sunday, 14 January 2018 03:19
Written by Christopher Carr
Hits: 2142

How do you reconcile a development workflow with the Agile methodology?

In the git feature branch workflow, all feature development takes place in a dedicated branch instead of in the master or develop branches.

In Agile, developent is performed in short sprints containing one or more user stories.

Using git, the recommended approach is to have one master branch which is the mainline and a develop branch where the development work is performed. When git is used in an agile shop, we can add some more helpful branches to facilitate the process, namely:

  • sprint - the sprint branch exists for the life of a single sprint. Suggested name for the sprint branch is sprint/nn where nn is the sprint number.
  • feature - from the feature branch workflow, each feature is developed in its own branch. Suggested name for each feature is <developer-initials>/<story-id>.
  • story - where more than one developer will be collaborating on a story, we create a story branch under which the developers can create their own feature branches. In this way, developers can use the story branch to share and merge their changes without impacting the sprint branch with their shared code changes until the work is completed.

develop

The Pit of Success

Details
Category: Tips
Published: Saturday, 13 January 2018 23:57
Written by Christopher Carr
Hits: 2291

Computers can outperform humans at an operational level at astounding speed. Yet they still only do what they are told.

Why is it then, that in Software Development, we repeat ourselves so often?

In Software Development, we should strive to make it impossible for us to fail.