Tips on writing good Git Commit messages

Photo by Yancy Min on Unsplash

Blog Post #006

Duncan Faulkner – February 2020

This post is slightly off my usual topics of Angular and Angular Material though its loosely linked to Angular I felt it was worthy of a post as this is something we do all the time.

I’ve been using Git for about five years or so now, and writing Git Commit messages can be hard (I would say this is just as hard as coming up with meaningful function and variable names in code), especially when trying to be consistent with the formatting of the message.

Follow me on Twitter to get notified about my newest blog posts!šŸ„

I’m sure we’ve all written commit messages like this, the way I have written them have all started like:

git commit -m "projName-jiraNumber - bug fix" 

git commit -m "projName-jiraNumber - more work" 

git commit -m "projName-jiraNumber - minor changes" 

git commit -m "projName-jiraNumber - work on feature X"

git commit -m "projName-jiraNumber - updated Y on..."  

At first these don’t appear to look that bad, you get a rough idea of the change. But when faced with hundreds of commit messages (and from different developers), finding a specific Commit in the Git History becomes that much harder.


Up until quite recently I hadn’t realised that you can provide multiple -m flags with a commit to add multiple commit messages.

Why would you want to add multiple messages to a commit?

Surely we can just cram everything into one message?

By adding multiple messages you can provide much more detail and be more specific about the commit, it doesn’t need to be an abbreviated or cryptic message that only you can remember what the commit was for.

Now, when reading a commit message in say GitLab, the first message becomes the Subject, the second message is the Body, the third message is the Footer (I’ll come to this in a bit), their values are concatenated as separate paragraphs.

git commit -m "projName-jiraNumber - fixed..." -m "body/description..." -m "footer..."

So this is a little better, adds more detail to the commit message, but we could improve this further by following a convention.

Conventional Commit Standard (I didn’t know that was a thing either!). This is a set of guide lines for creating Git Commit messages that follow a particular format.

The format is:

type(scope):subject
BODY
FOOTER

Each commit message consists of a header, body and footer. The header is mandatory, scope is optional, subject is mandatory. When writing a commit message try and limit each line of the commit to a max of a 100 hundred characters, so it can be read easily on GitLab etc…

Type

The type must be one of the following:

  • build: Changes that affect the build
  • ci: Changes to our CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

Revert

If a commit reverts a previous change then the type should begin with revert: and the body should explain what this change is reverting.

Scope

The scope refers to the section that this commit belongs to Components, Services, Directives, Pipes for example user-component, user-service, user-directive etc.. Other scopes include changelog, styles, test and refactor.

Subject

The subject should contain a short description of the change, and written in present tense, for example “change” and not “changed” or “changes”.

Body

The body should contain a longer description of the change, try not to repeat the subject and keep it in the present tense as above.

Footer

The footer is used to highlight where issues have created a breaking change in your commit. The footer should start with BREAKING CHANGE: the body should contain a description of the breaking change.

The footer can also be used to reference other issues, for example: “Fixes ticket #123”.


Examples

A few examples of Git Commit messages using this new format:

feat(order): add a save button
add the save button to the sales order form

docs(manual): document the order process
create new document explaining the sales order process

fix(user): update the user menu
update to the user menu to fix the broken menu item

fix(user-service): change save method in API
BREAKING CHANGE: change to the save method to include additional parameters


Follow me on Twitter to get notified about my newest blog posts!šŸ„

Let me know in the comments what you think to this format.

Setting up an Angular Project

Blog Post #005

Duncan Faulkner – February 2020

I find myself repeating the Angular setup process at the start of most posts I write. So to save time. I will write it out here and reference this post when referring to setting up an Angular application in the future.

This will be a standard setup, for setting up a project with NX Workspaces see my previous post here.

Step one:

Open a terminal and create a directory to store our application in.

cd development
mkdir myproject 
cd myproject

Step two:

If you have nvm, node and the angular cli installed you can skip this step.

To install node.js, you could install this from nodejs.org, but for greater flexibility, I find installing node version manager (nvm), will save a lot of hassle next time you need update node.

Note: Remember to check the version number and update this in the scripts below, at the time of writing this was v0.35.2, it may be different.
Note: You only need to run one of these.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash

or

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash

Once installed you should be able to check the version, in the terminal type:

nvm --version
0.35.2

Now we have nvm installed we can install node. Again from the terminal type:

nvm install #and the version of node you want to install, for example:
nvm install 12.14.1

#Other useful nvm commands are:
nvm ls #this will list all installed versions of node
nvm use 12.6.0 #will use this version of node.

nvm alias default v9.3.0 #this will set the default version.

Now we have node installed we can now install angular cli, from the ternimal type:

npm install -g @angular/cli 

This will install the angular cli globally, as denoted by the -g. After installation is complete check the version of angular by typing:

ng v
angular version printed out in console
screen shot of angular version

Step three

Now that’s all setup, lets create a project, in the terminal type:

ng new my-first-project

The angular cli will ask the following questions.

? Would you like to add Angular routing? (y/N) y

 CSS
>SCSS [https://sass-lang.com....] #select this one
 Sass [https://sass-lang.com...]
 Less [http://lesscss.org...]
 Stylus [http://stylus-lang.com...]

That should start the process off and it will install all the dependencies and create our project. You may see some warnings at the end of the install, these are dependencies they may need to be updated, which we will do at the end. For now switch to the my-first-project directory and open up VS Code.

cd my-first-project
code-insiders .
my-first-project shown in vs code

And that’s all there is to it.

Step four

Update the project to the latest versions. In the terminal type:

ng update #this will list any packages that have an update available.

This will check to see if there are any updates, if there are then run:

ng update --all

#there are a couple of additional flags that can be used (with caution!) these are:

ng update --all --allow-dirty #this allows the update to happen when the current branch (if using version control) has not been checked in

ng update --all --allow-dirty --force #this will force the updates, though chances are compatibility will be broken and you may need to roll some packages back to a previous state. 

There is a good chance that this will fail, mainly because there are newer versions of certain packages that would break compatibility.

The next step would be to add Angular Material to the project. For that I will create a separate post so as to keep this purely for the standard setup.

Thanks for reading enjoy…


Previous Posts

Using the …SpreadOperator

Blog post #004

Duncan Faulkner – February 2020

Recently I’ve found myself looking at ways I can improve the reading of my code. Just little things, just to tweak this or that just to make the code a little more easier on the eye.

Recently I’ve started using the spread operator (…) as I find this looks a lot cleaner and makes code easier to read.

In this post I’m going to show you how to use the spread operator in your Angular module files.

Most of the module files I’ve written have all looked the same. Starting at the top of the file are the Imports, followed by the NgModule with some or all of the following: Imports, Exports, Declarations, Entry Components and Providers.

Depending on the number of imports into the module this can have a lot of repeated code. So these files are ideal for the spread operator, reducing the repeated code. Lets see and example.

import { MatAutocompleteModule } from '@angular/material/autocomplete';
import { MatButtonModule } from '@angular/material/button';
import { MatButtonToggleModule } from '@angular/material/button-toggle';
import { MatCardModule } from '@angular/material/card';
import { MatCheckboxModule } from '@angular/material/checkbox';
import { MatChipsModule } from '@angular/material/chips';

import { NgModule } from '@angular/core';

@NgModule({
  imports: [
    MatAutocompleteModule,
    MatButtonModule,
    MatButtonToggleModule,
    MatCardModule,
    MatCheckboxModule,
    MatChipsModule
  ],

  declarations: [],
  exports: [
    MatAutocompleteModule,
    MatButtonModule,
    MatButtonToggleModule,
    MatCardModule,
    MatCheckboxModule,
    MatChipsModule
  ],
  entryComponents: [],
  providers: [MatIconRegistry]
})
export class MaterialModule { }

The above example is from the Mat-Icon material module file and shows the same things repeated three times in this example. Lets refactor this code.

import { MatAutocompleteModule } from '@angular/material/autocomplete';
import { MatButtonModule } from '@angular/material/button';
import { MatButtonToggleModule } from '@angular/material/button-toggle';
import { MatCardModule } from '@angular/material/card';
import { MatCheckboxModule } from '@angular/material/checkbox';
import { MatChipsModule } from '@angular/material/chips';

import { NgModule } from '@angular/core';

const MODULES = [
  MatAutocompleteModule,
  MatButtonModule,
  MatButtonToggleModule,
  MatCardModule,
  MatCheckboxModule,
  MatChipsModule
];
@NgModule({
  imports: [
    ...MODULES
  ],
  declarations: [],
  exports: [
   ...MODULES
  ],
  entryComponents: [],
  providers: [MatIconRegistry]
})
export class MaterialModule { }

Now, unfortunately the Angular Material imports need to be individually imported for each feature separately, but it does reduce the code (a bit) and it does help with having just one copy to manage, lets have another example, that I have changed to use the spread operator (you should be able to visualise what this looked like before).

import { NgModule } from '@angular/core';
import { VendorModule } from './vendor.module';

import {
  AnalysisComponent,
  ChartComponent,
  IconComponent,
  PodComponent,
  SpinnerComponent,
  TermsComponent,
  ChangePasswordComponent
} from './components';

import {
  PortPipe,
  NumericPipe,
  AsteriskPipe,
  SplitIpPipe,
  RemoveUnderscorePipe,
  AddUnderscorePipe,
  FormatBytesPipe
} from './pipes';

import { NumberDirective } from './directives';

const COMPONENTS = [
  AnalysisComponent,
  ChartComponent,
  IconComponent,
  PodComponent,
  SpinnerComponent,
  TermsComponent,
  ChangePasswordComponent
];

const PIPES = [
  PortPipe,
  NumericPipe,
  AsteriskPipe,
  SplitIpPipe,
  RemoveUnderscorePipe,
  AddUnderscorePipe,
  FormatBytesPipe
];

const DIRECTIVES = [NumberDirective];

const MODULES = [VendorModule];

const ENTRYCOMPONENTS = [TermsComponent, ChangePasswordComponent];

@NgModule({
  imports: [...MODULES],
  declarations: [...COMPONENTS, ...PIPES, ...DIRECTIVES],
  exports: [...COMPONENTS, ...PIPES, ...DIRECTIVES, ...MODULES],
  entryComponents: [...ENTRYCOMPONENTS],
  providers: [...PIPES]
})
export class SharedModule {}

In the example above, imports for the component, pipes and directives are all grouped together. Constants are configured, and used in the NgModule section of the file . The important part of this file is the NgModule section and you can easily now read that section without all the clutter of all the various components, pipes and directives all over the place.

The spread operator include options for object destructing, rest params and array destructing (as shown above).

Thanks for reading!


Previous Posts…

Using Mat-Icon Component – Part Two

Blog Post #002

Duncan Faulkner – January 2020

I hadn’t intended to write about this just yet, but I got a chance to investigate this sooner than I had thought. I was refactoring part of a project that was using the Mat-Icon component, with an icon.module.ts file as I’d discussed in the previous post.

I wanted to see if I could improve on the code and reduce the amount of repeated code by iterating over a file and registering the icons.

I started with a JSON file and populated it with some image names and added the HttpClientModule to use an http.get() method to read the JSON file. All good so far, the file is reading and looping with image names being returned and passed into the matIconRegistery.addSvgIcon() method.

I thought I might get some issues, but it all seemed to work fine, except the application was erroring, the issue was that the application was loading before the call to the JSON file had returned with the results, so even though I was getting images and registering icons, the app had already tried to use the icons and they weren’t there at that point, and the images were being returned after the app had started.

OK, so may be this is a timing issue and it doesn’t work in the icon.module.ts file, so I moved code to the app.component.ts file. Nope, the results were the same. This was not the result I was expecting and it was a little odd because the icon.module.ts file was loading images before.

I’m going to revisit this at a later date, as I would like to understand what the issue is and why it was behaving the way it did, my guess is it has something to do with the http.get() request and the timing around that.

But as I needed to get this refactoring completed I needed to look for another solution.

After a bit of research I found an answer and that was to create a service to handle the iterating and registering of icons. Instead of a JSON file to store a list of images the solution was an enum, with a key value structure.

export enum Icons {
    add = 'add',
    power = 'power',
    save = 'save'
}

To keep things simple I’ve made the key and the image name the same.

The service is quite simple:

// imports
import { Icons } from '../image.enum';

@Injectable({ providedIn: 'root'})
export class IconService {
  constructor(
     private matIconRegistry: MatIconRegistry,
     private sanitizer: Domsanitizer
){}

registerIcons(): void {
   this.load(Object.values(Icons), 'assets/images/icons');
}

private load(key: string[], url: string): void {
   key.forEach(icon => {
     this.matIconRegistry.addSvgIcon(
       icon, 
       this.sanitizer.bypassSecurityTrustResourceUrl(`${url}/${icon}.svg`)
   ); 
 });
 }
}

And on the app.component.ts file call the registerIcons() function.

// imports
import { IconService } from './icon.service';

export class AppComponent implements OnInit {
   constructor(private iconService: IconService) {
      this.iconService.registerIcons();
   }

}

And that’s it, not what I had in mind when I started this, but it does deliver what I wanted to do, and that was to reduce the amount of code to register icons. Though I guess the enum could get pretty lengthy if there are a lot of images.

I have to thank Stefanos Kouroupis -dev.to – for his article and code on this as I wouldn’t have thought about using a service for this and this has changed my thinking. I wanted to include here it as a follow up to my previous post for completeness, you can see his full article here https://dev.to/elasticrash/using-custom-made-svg-icons-through-the-angular-material-library-2pif.

I will add a github repo of the code in a day or two.


Previous posts…

Angular Materials Mat-Icon component

Using local SVG images.

Blog post #001

Duncan Faulkner – October 2019

When developing an Angular application with Angular Material, there comes a point when we need to add icons on our components, or buttons etc… Angular Material has the Mat-Icon component for doing this. This component works with web fonts like Font-Awesome for instance, simply by adding the name of the image required and an image is displayed.

For example: <mat-icon>home</mat-icon>

Note: Requires Angular application and Angular Material is installed/configured and a reference to a web font like Font-Awesome library is all set up

But what about if you have custom icons that are not part of a web font? And would like to makes changes to the icon, for example: change the colour on hover or on a specific condition at run time?

In a recent project I had a bespoke set of SVG icons, the Angular web application was to be installed on a server that didn’t have access to the internet, so the images had to be local. I wanted to use the Mat-Icon component out of the box (in an early version of the project I had a custom icon component). I still wanted to be able to change the colours of the icons at various stages throughout the application based on certain conditions as well as on hover. This post covers how I achieved that.

SVG Icons

There are a number of different ways to register an icon with the Mat-Icon component, this post discusses addSvgIcon, the others are addSvgIconInNamespace, addSvgIconLiteral or  addSvgIconLiteralInNamespace and are all methods of  MatIconRegistry and I might cover these in more detail in a future post.

Setting up an Angular project

Note In this post, I’m not going to step through the creation of an Angular application as there are so many already online. Plus I tend to create Nx workspaces for all my Angular projects as I prefer this project layout. I plan to do a blog post on this very soon, for the moment though see Getting started with Narwhal’s Nx Workspaces.

In the newly created Angular project, create a shared directory and add a new file named material.module.ts. I like to separate Angular Material imports into their own module, I also create a separate module for other 3rd party components, just makes it easier to import later, especially using the NX workspace layout and feature folders.

// Material Module example.
 // All other Angular Material component imports here
 // but the important ones areā€¦
 import { MatIconModule, MatIconRegistry } from "@angular/material/icon";
 @NgModule({
   declarations: [],
   imports: [
     // Other material imports removed for brevity,
     MatIconModule
   ],
   exports: [
     // Other material exports removed for brevity,
     MatIconModule,
     MatIconRegistry
   ],
   entryComponents: [],
   providers: [MatIconRegistry]
 })
 export class MaterialModule {}

MatIconModule is the module for the component, and the MatIconRegistry is a service to register and display icons. Add a reference to theĀ material.module.tsĀ in theĀ app.module.ts. Don’t forget to export it as well, otherwise it won’t be available and Angular will not know anything about the Angular Material components.

// Include the material module in app.module.ts
import { BrowserModule } from "@angular/platform-browser";
import { NgModule } from "@angular/core";
import { AppComponent } from "./app.component";
import { BrowserAnimationsModule } from "@angular/platform-browser/animations";
import { MaterialModule } from "./shared/material.module";

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, BrowserAnimationsModule, MaterialModule],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {}

Now we have the Angular Material components set up and configured we need to register the icons, before we can use them. For the moment we are just going to add these to theĀ app.component.tsĀ to get up and running, we’ll look at a better method later on.

// First Example
@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.scss"]
})
export class AppComponent {
  constructor(private matIconRegistry: MatIconRegistery) {
    this.matIconRegistry.addSvgIcon("home", "assets/img/icon/home.svg");
    this.matIconRegistry.addSvgIcon("add", "assets/img/icon/add.svg");
  }
  // or we could do this, and chain the addsvgIcon methods.
  // we'll use this method going forward in this post
  // {
  //  this.matIconRegistry.addSvgIcon('home','assets/img/icon/home.svg')
  //  .addSvgIcon('add','assets/img/icon/add.svg');
  // }
}

Add this to theĀ app.component.htmlĀ page, we’ll discuss this in more detail in a bit.

<!-- First HTML example -->
<div>
     <mat-icon svgIcon="home"></mat-icon>
     <mat-icon svgIcon="add"><mat-icon>
</div>

At this point we are not going to see much in the browser as we have an issue with the image URL. If you open the browsers console section, you will see the following error:

Error: unsafe value used in a resource URL context.

So what does this error mean? A brief explanation from the Angular Material website says:

To prevent an Cross Site Scripting (XSS), SVG URL’s and HTML strings passed to MatIconRegistry must be marked as trusted by the Angular’s DomSanitizer service. Icons are fetched via XmlHttpRequest and must have their URL’s on the same domain as the containing page or configured to allow cross-domain access.

So lets add the DomSanitizer and fix this issue.

// Second Example - with the DomSanitizer
@Component({
 selector: 'app-root',
 templateUrl: './app.component.html',
 styleUrls: ['./app.component.scss']
})
export class AppComponent {
 constructor (
 private domSanitizer: DomSanitizer,
 private matIconRegistry: MatIconRegistery
 ){
 this.matIconRegistry
 .addSvgIcon('home',this.domSanitizer.bypassSecurityTrustResourceUrl('assets/img/icon/home.svg')
 .addSvgIcon('add',this.domSanitizer.bypassSecurityTrustResourceUrl('assets/img/icon/add.svg')
 // add other icons here....;
 }
}

The call to bypassSecurityTrustResourceUrl takes a URL as a parameter and sanitises it so that an attacker cannot inject a ‘JavaScript:` URL for example, see official documentation on DomSanitizer. Now that we have this in place we should now see two icons in the browser.

If we have a lot of icons to add this means lots of typing and lots of repetitive code, so lets refactor this some more. Start by removing all of this code (including the constructor) from the app.component.ts. This shouldn’t really be in the app.component.ts file. Lets create another new module in the shared directory and call itĀ icon.module.tsĀ and then add the following:

// Third Example - icon module
import { NgModule } from "@angular/core";
import { DomSanitizer, SafeResourceUrl } from "@angular/platform-browser";
import { MaterialModule } from "../shared/material.module";
import { MatIconRegistry } from "@angular/material/icon";
@NgModule({
  declarations: [],
  imports: [MaterialModule],
  exports: [],
  providers: []
})
export class IconModule {
  private path: string = "../../assets/images"; // change this
  constructor(
    private domSanitizer: DomSanitizer,
    public matIconRegistry: MatIconRegistry
  ) {
    this.matIconRegistry
      .addSvgIcon("home", this.setPath(`${this.path}/home.svg`))
      .addSvgIcon("add", this.setPath(`${this.path}/file-plus.svg`));
  }
  private setPath(url: string): SafeResourceUrl {
    return this.domSanitizer.bypassSecurityTrustResourceUrl(url);
  }
}

Overall, that’s not too bad. We are only writing out the domSanitizer code once in the private method but more importantly, all the code is out of the app.component.ts file and is now a self contained module. If there are a lot of icons to add then this file will get a bit long, but the typing has gotten shorter (well, a little shorter at least). You could change the constructor to iterate through a .json file of image names, the path wouldn’t change and could be a const, which would only mean maintaining a .json file with any new images. I might look at doing that in a follow up post.

Note: Don’t forget to add this new icon.module.ts to the app.module.ts otherwise it won’t work.

Using the Mat-Icon component

So how do we use the mat-icon component? As seen earlier in this post we add the following code to our app.components.html page.

<!--First HTML example-->
<div>
    <mat-icon svgIcon="home"></mat-icon>
    <mat-icon svgIcon="add"></mat-icon>
</div>

This is a very simple example is showing how to put a home and an add icon on a page/component. This is not too dissimilar to how we would use this component with web fonts, but we are now using the svgIcon input property. The value we give to this input is the first parameter used in our call to register the .addSvgIcon(‘home’, …) in this case home.

Now we have an icon in place, how do we change the colour of the icon when someone hovers over it for example?

Change the icon colour

A Home icon. Example icon copy this into a file with the SVG extension.

<svg version="1.1" width="24" height="24" viewBox="0 0 24 24"><path d="M10,20V14H14V20H19V12H22L12,3L2,12H5V20H10Z" fill="#00FFFF"></svg>

In the above XML, I’ve removed all the namespaces etc… The main part here is the fill=”#00FFFF”. This sets the colour for the image, in this case to AquaMarine.

If the fill=”#00…” property is not there and you want a different colour to the default black, then you can add it to the path as above. It’s optional.

I usually add theĀ fillĀ property and set it to white and then change it, in SCSS as and when required (because this example had a white background I used another colour).

!<-- Second HTML example -->
<div>
  !<-- other code omitted for brevity -->
  <a mat-button>
      <mat-icon svgIcon="home" class="btn-icon"></mat-icon>
  </a>
</div>

Add a class to the mat-icon html tag, as above. Next, add the SCSS for the class so that, when a user hovers over the button the colour of the icon changes.

.btn-icon {
  &:hover {
    path {
      fill: rgba(#00ffff, 1);
    }
  }
}

Note:Ā One thing I did forget to add to the app.component.ts above, was the following line:Ā encapsulation: ViewEncapsulation.None, without this then the hover affect doesn’t work.

@Component({
  selector: "mat-icon-demo-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.scss"],
  encapsulation: ViewEncapsulation.None
})
export class AppComponent {
  title = "mat-icon-demo";
}

Enjoy!

There is a github repo for this blog post at: https://github.com/Anglebrackets-io/mat-icon-demo


Previous posts…