JAFDIP

Just another frakkin day in paradise

Archives for July 2020

Ruling Git Commits and Branches

Managing a team of developers changes the way you approach even some of the simplest things. For instance years ago when Git was young and even subversion (SVN) was relatively new, I remember one developer who’d only ever worked as a freelancer complain about being forced to use version control. He lamented why can’t we just FTP my files into the server because he couldn’t think outside the scope of how he’d always done things on his own.

CI/CD is not the technology that facilitates the continuous integration or delivery; it is the philosophy agreed upon by the team practicing CI/CD. The technology enables that team to manage their CI/CD contract without having to think about it on a daily basis.

Mikel King

Even after I explained the dangers of FTP and championed the benefits of SFTP, he still couldn’t, possibly wouldn’t, understand the benefits of version control and deployment scripts. Not that day but soon in the near future he learned the hard way. We were a small team only three developers working on a large project and on that occasion something when wrong and I had to redeploy the entire site from the version control system from a previous stable released version. He admitted that he could not have easily done this with his personal zip file versioning especially accounting for the other developer’s work in the code base.

So fast forward from the early heady days of simplistic version control and team management. Quite a lot has changed. Whether you you Git, SVN, Mercurial, or even the dreaded CVS the fact of the mater is that most teams could not accomplish delivery under tight deadlines without this seemingly basic tool. While this article will focus on git and more specifically GitLab the concepts presented should be transportable into other systems.

As you grow form a solo developer into a team you discover relatively quickly that you need to coalesce as a unified team on conventions that make the job of managing your project possible. I have said this many times before and I shall say it again CI/CD is not the technology that facilitates the continuous integration or delivery; it is the philosophy agreed upon by the team practicing CI/CD. The technology enables that team to manage their CI/CD contract without having to think about it on a daily basis.

So getting back to GitLab let’s discuss push rules which are only available on paid plans. They are well worth the price of admission and if you have a paid plan and are not using them you have over looked a simple tool to help you rein in your wild development team. For the sake of argument let’s say that your team has agreed on some form of GitFlow as part of the SDLC.

So you make your feature branches and sometimes you deploy and you end up having hotfix branches and of course you have develop, and release and master but everything is on a kind of grand scale honor system. Wouldn’t is be great as you onboard new team members that you process kind of enforced itself? I mean if you could just point them at the team process docs and pretty much cut them loose after a short shadowing period?

Let’s get started shall we?

Go to repository under settings as shown below.

You will see a page similar to the following and you will want o expand the section labeled Push Rules.

In the entry field labeled Commit message you need to enter a regex that defines the rule you want to enforce. We are starting with commit message rules because they are generally easier to work out than branch rules. In my team’s case we have agreed that ALL commit message need to start with a issue identifier followed by a ‘:’. In our case we use Jira so if the issue I was working on is was number 12345 on the the DevOps board then I would my commit message would look like, ‘DO-12345: I did some important stuff.” The following rule actually would prevent me from pushing my commit to origin if it did not match the format specified.

^((WP|wp|DO|do|PRX|prx|AD|ad|DATA|data|DPT|dpt)(-)(\d*)(: )|Merge|Auto)

I could have been lazy and used simple alph character rule like [a-z],[A-Z]+ but I wanted to explicitly define the allowable ticket prefixes. In addition I added a Auto for all of our automated build scripting that auto generate relatively generic commit messages. Finally I added Merge because merging two branches produces an auto merge commit message which you could easily override with the -m cli option but I really don’t see the need.

So that’s how to enforce commit message integrity. I can not guarantee that your developers will add a meaningful message but at least things will synchronize better. So let’s turn out attention to branch naming rules, in the Branch name field we will add a more complex rule.

^((feature|hotfix|patch|companion|)\/
((WP|wp|DO|do|PRX|prx|AD|ad|DATA|data|DPT|dpt))(-)
(\d*)|develop|release|stable|princess|master)

The above rule (modified to fit the content window) functions very similarly to the commit message rule however GitLab will reject any branch push to origin if it’s name does not pass this rule. Again for much of our work we rely on the aligning out branches to the issue tracking system. From our previous example above the corresponding appropriately named branch would feature/do-12345.

It’s relatively trivial to parse the feature/do-12345 branch name through the rule now that we’ve examined the commit message rule and upon careful inspection you can see that the rule aligns with GitFlow’s feature and hotfix nomenclature. However you will also not that we have two additional branch prefixes patch and companion which are unique to our process (see The Tao of Releasing).

In addition the rule allows for iterative variation on the branch naming. For instance if I have completed work on in the feature/do-12345 branch and need to try a slightly different approach I can create a feature/do-12345-a branch that will still satisfy the rule. I could even use a name like feature/do-12345-mk-crazy-idea for the branch alternative name. Thus you can see that the rules enforce a minimum level of conformity.

The final part to note about the branch naming is that the rule has been crafted to account for intrinsically named branches. These are branches tied to our various deployment environments and special purpose states of completion. If I did not include them then we would not be able to release finished products and that would kind of defeat the whole purpose of this exercise.

I hope you have enjoyed this look at commit message and branch naming rules enforcement with GitLab. While you can roll your own precommit and push hook scripts GitLab makes it easy through their interface. In either case if properly used in conjunction with other tools like a well defined coding standard and a thoroughly mapped SDLC process then you will find it is far easier to manage and scale you team(s). We will examine more of these in future articles.

Building a Basic Plugin

In order to make plugin building as streamlined as possible we build our plugins out of Bacon. Bacon is a framework built as WordPress library of mu-plugins. In the mu-plugins directory is a plugin-stub that contains the basics for building a discreet plugin.

Simply cd into your plugins directory and execute the following;

cp -r ../mu-plugins/plugin-stub hm-new-plugin-name

Upon completion enter the rd-new-plugin-name directory and edit plugin.php identifier block and rename the class as appropriate. Remember to properly instantiate your new plugin or you will cause a PHP FATAL execution error, resulting in a White Screen of Death (WSOD).

If you intend on including other assets like css, fonts, images, javascript you should follow the standard plugin file system hierarchy (see below).

This image has an empty alt attribute; its file name is plugin-hiearchy.png

Using this hierarchy ensures consistency and familiarity for the rest of the development team. The goal of using a framework is to work within it’s confines because consistency helps reduce long term technical debt. The Bacon framework has been designed to ensure flexibility while promoting PHP clean coding standards.

Most plugins and their internal files will extend the WP_Base class. Following this convention ensure we use the standard methods and format for registering CSS & JS. Depending on the location with you classes registration method for example if you are registering JS withing the plugin.php in the root of you plugin then you would define the file spec as follows:

const FILE_SPEC = FILE;

However is this were to happen in a php file inside of inc then use the DIR magick constant. In either case this simple constant sets up the built-in get_asset_url() method.

const FILE_SPEC = DIR; 
public function register_scripts() { 
  wp_register_script( 
    self::SCRIPT_NAME, 
    $this->get_asset_url( self::SCRIPT_FILE ), 
    $this->depends, 
    self::VERSION, 
    self::IN_FOOTER 
  ); 
  wp_enqueue_script( self::SCRIPT_NAME );
}

Also note the expanded the function call structure. We have found that expanding the call out like this reduces eye strain and greatly enhances code review efficiency.

Finally observe the named constants. We do this to ensure maximum readability and expedited interpretation. Take the last parameter to wp_register_script() which is a bool and depending upon whether it is set to true of false changes the destination of the script when it is finally enqueued. When you are writing or reviewing code you honestly should not waste time trying to remember the difference. By using the constant we have clearly defined the value as well the intended outcome in an unchanging manner.