On Semantic Versioning

First of all, you should know that versioning is important.  Even the worst versioning practices provide more value than no versioning at all.  At work, we are big fans of the Semantic Versioning, and we use it for all our projects, plugins, and libraries.  And I think, you should do too.

In general, Semantic Versioning works great for us.  But there were a few bumps recently, with more and more libraries dropping support for PHP 5.6 and requiring PHP 7.  I can’t blame them – after all PHP 5.6 has reached its end of life quite a while ago.

It’s not what the maintainers do, but how they do it that I have an issue with.  I’ve been thinking about writing a blog post on the subject for a few month now.  Never got to it.  And yesterday I came across this blog post by Paul Jones, which is so much better than whatever I was about to say.  Paul explains the problem in detail and suggests the “System” addendum to Semantic Versioning:

I opine that requiring a change in the public environment into which a package is installed is just as major an incompatibility as introducing a breaking change to the public API of the package. To cover that case, I offer the following as a draft addendum to the SemVer spec:

  • If the package consumer has to change a publicly-available system resource to upgrade a package, then the package upgrade is not backwards-compatible with the existing system, and the package SHOULD receive a major version bump.

Using “SHOULD” makes this rule somewhat less strict than the MUST of a major version bump when changing the package API.

Coming back to PHP 5.6 vs PHP 7, that would suggest that maintainers who drop support for PHP 5.6 SHOULD bump up the MAJOR release of the library.   And I wholeheartedly agree with that!

P.S.: For those of you who don’t or can’t use Semantic Versioning for whatever reason, checkout Paul’s blog post on Semantic Versioning vs. Romantic Versioning.

Clean Code SOLID principles applied to PHP

clean-code-php is an excellent set of examples for the SOLID principles as applied to PHP programming:

Software engineering principles, from Robert C. Martin’s book Clean Code, adapted for PHP. This is not a style guide. It’s a guide to producing readable, reusable, and refactorable software in PHP.

Not every principle herein has to be strictly followed, and even fewer will be universally agreed upon. These are guidelines and nothing more, but they are ones codified over many years of collective experience by the authors of Clean Code.

Inspired from clean-code-javascript

pre-commit – a framework for managingmulti-language git pre-commit hooks

From the pre-commit homepage:

Git hook scripts are useful for identifying simple issues before submission to code review. We run our hooks on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. By pointing these issues out before code review, this allows a code reviewer to focus on the architecture of a change while not wasting time with trivial style nitpicks.

As we created more libraries and projects we recognized that sharing our pre-commit hooks across projects is painful. We copied and pasted unwieldy bash scripts from project to project and had to manually change the hooks to work for different project structures.

[…]

We built pre-commit to solve our hook issues. It is a multi-language package manager for pre-commit hooks. You specify a list of hooks you want and pre-commit manages the installation and execution of any hook written in any language before every commit. pre-commit is specifically designed to not require root access.

Have a look at the list of all supported hooks. There’s plenty!

Passwords Evolved: Authentication Guidance for the Modern Era

Passwords Evolved: Authentication Guidance for the Modern Era” is a good collection of guidelines and concerns for password management in the modern day.

Here’s the bigger picture of what all this guidance from governments and tech companies alike is recognising: security is increasingly about a composition of controls which when combined, improve the overall security posture of a service. What you’ll see across this post is a collection of recommendations which all help contribute to a more robust solution by virtue of complimenting one and other. That may mean that individual recommendations such as dropping complexity requirements look odd, but when you consider the way humans tended to deal with that (they’d just choose bad passwords with a combination of character types) alongside guidance such as blocking previously breached passwords, things start to make a lot more sense.

Now there’s just one more thing: as good as all this guidance is, practically implementing it can be somewhat trickier.

The Minimally-nice Open Source Software Maintainer

Brian Anderson shares a few thoughts on how to appear as a minimally-nice Open Source Software maintainer.  Maintaining Open Source Software projects is a demanding job.  And the more popular the project is, the more demanding it is.  Brian shares the following practices that minimize the effort while you still maintaining a positive atmosphere for the project’s contributors:

In summary, do these things if you want to appear to be nice, and also if you want to actually be an effective open source software maintainer:

By consistently exhibiting a few simple behaviors, one can at least look like a kind and decent person. Maybe someday we all actually will be.

Using non-breakable spaces in test method names

Using non-breakable spaces in test method names is a great example of how something can start as a joke and quickly turn into something very practical and useful.

if we decide to not follow PSR-2 naming for test methods because of readability, we might as well use non-breakable spaces since it’s even more readable…

Real Favicon Generator

Real Favicon Generator is a handy tool for setting up your website’s favicon properly.  It takes care of both the images (formats, resolutions, etc) and the HTML that you’ll need to include.  With just a few clicks your website will work properly with browsers, operating systems, and mobile applications.

With so many platforms and icons, it’s hard to know exactly what you should do. What are the dimensions of favicon.ico? How many Touch icons do I need? RealFaviconGenerator did the reseach and testing for you.

If you still prefer to do it yourself and know all there is to generating proper favicon images and markup, have a look at this resource for everything there is to it and more.

Git Commit Good Practice

Open Stack wiki has an excellent guide on how to create good commits.  In a few places it is too specific to Open Stack development practices, but overall it’s one of the best guides I’ve seen for any project using git.

It is basically split into two sections.  One on how to decide which code goes into the git commit, and the other is what to include in the git commit message to make it useful.

The first part is simpler:

The cardinal rule for creating good commits is to ensure there is only one “logical change” per commit. There are many reasons why this is an important rule:

  • The smaller the amount of code being changed, the quicker & easier it is to review & identify potential flaws.
  • If a change is found to be flawed later, it may be necessary to revert the broken commit. This is much easier to do if there are not other unrelated code changes entangled with the original commit.
  • When troubleshooting problems using Git’s bisect capability, small well defined changes will aid in isolating exactly where the code problem was introduced.
  • When browsing history using Git annotate/blame, small well defined changes also aid in isolating exactly where & why a piece of code came from.

With these things to avoid:

  • Mixing whitespace changes with functional code changes.
  • Mixing two unrelated functional changes.
  • Sending large new features in a single giant commit.

The second part is slightly more detailed.  Here’s the information that should be included in the commit message, generally speaking (abbreviated quote):

As important as the content of the change, is the content of the commit message describing it. When writing a commit message there are some important things to remember

  • Do not assume the reviewer understands what the original problem was.
  • Do not assume the reviewer has access to external web services/site.
  • Do not assume the code is self-evident/self-documenting.
  • Describe why a change is being made.
  • Read the commit message to see if it hints at improved code structure.
  • Ensure sufficient information to decide whether to review.
  • The first commit line is the most important.
  • Describe any limitations of the current code.
  • Do not include patch set-specific comments.

In other words, if you rebase your change please don’t add “Patch set 2: rebased” to your commit message. That isn’t going to be relevant once your change has merged. Please do make a note of that in Gerrit as a comment on your change, however. It helps reviewers know what changed between patch sets. This also applies to comments such as “Added unit tests”, “Fixed localization problems”, or any other such patch set to patch set changes that don’t affect the overall intent of your commit.

Read the whole thing for more details, examples of good and bad practices, and more specific instructions on the spacing, line length, and more.

And if you need more convincing or a different explanation, then Google “git commit best practices” or simply check out some of these resources: