Paul Hammant's Blog: Often forgotten must-haves for Continuous Delivery teams

Some dev teams are in arrears on two things that are essential for high-competency teams. Things that newbies are going to need if they are joining the team a few weeks or months after everyone else.

I use ‘Continuous Delivery’ here because enterprise teams are questing to get there, and these two are freebie advice:

READMEs

The Readme is a file called README.md in the root of the clone. The developers can read it in-situ on Github, AtlassianStash or GitLab formatted into HTML (from markdown). Or they can read in in the workspace with any text-reading command line tool or suitable application, including IDEs. It is open for contribution as any source file is in a clone/checkout, and goes back in the same way commit/push.

The readme should be worked on from the minutes following the creation of the project/repo. If should also be reviewed every day thereafter for correctness and completeness. The principle is that a developer (or QA automator) should be able to clone, build and open the project in IDEs without asking anyone else what the steps are.

Command line ‘first’

This one is more of a forgotten aspect of Enterprise development, where Eclipse and home-made plugins may dominate. Teams are so used to a reliance on the IDE that the skills to do every fine-grained build operation on the command line has been forgotten. Your lowest common denominator is the command line, and if all else is missing vi/emacs/pico/nano/micro are the supported editors. Of course, we go in a JetBrains IDE if we can these days, but that should be secondary to the command line.

Joel had it right with “Can you make a build in one step?” Refer to The Joel Test. Step isn’t called out to be a command line step, but that was Microsoft’s practice for all of the 90’s prior to commit. 1995’s Microsoft’s Secrets goes into that. Only with IDEs later, did team slowly transition to over-reliance on the the IDE for build/test functions, prior to committing. IDEs were always meant as a supplement to command line skills, and never as a replacement for them.

We touched on pre-commit there. It is essential that a team-agreed one step build is run prior to committing the code. And the team should not claim that that is ‘compile only’ - there has to be at least one round of tests in there.

The command line interface is doubly important to us when we remember that our choice of CI tool also utilizes the same know how. Jenkins (etc) may provision a whole build environment via scripts afresh each time, though, rather than pre-setup a Mac/PC for human development.

When that CI daemon notices the commit it should be running the same build to guard the application/service’s functional correctness in the same way that the developers and QA automators do pre-commit.

Update (Dec 2017)

Site makeareadme.com exists :)