Growing a development process

How can you grow a process that meets your needs?

• use version control and develop on branches;
• create a checklist to use when merging branches into master;
• follow the checklist!

(For more checklist motivation, see The Checklist Manifesto by Atul Gawande.)

We do the above as part of our GitHub flow-based development approach.

tl;dr? Grow your checklist slowly, but make everyone adhere to it.

What goes on your checklist?

Ideas for things that could go on your checklist:

• I ran the tests and they passed!
• Someone else ran the tests and they passed!
• A computer ran the tests automatically and they passed! (Continuous Integration)
• The code formatting guidelines are met. (> 2 people with different coding styles? CHAOS.)
• The code coverage guidelines are met.
• A spellchecker was run.
• Changes were described in a ChangeLog.
• Commit messages make sense.
• Code coverage didn't decrease.
• Checks on specific types of features ("Script parameters should be documented").

I also strongly suggest a two-person merge rule (the primary developer of a feature can not merge that feature); this helps ensure the checklist is followed :)

You can see our checklist for khmer here.

---

It's important to make the checklist as lightweight as possible, and making sure it addresses useful "pain points" in your developer process; there's a line where people start ignoring the checklist because there's less direct value.

There's no reason to start heavy; you can grow your checklist slowly, as your project accrues experience and developers turn over.

---

Development process goals

Add features quickly (by using branches) while keeping technical debt manageable!

The concept of technical debt is key - if you let cruft accrue in your codebase, eventually your entire codebase will become unmaintainable and unmanageable.

Other useful links:

• the Software Sustainability Institute's evaluation checklist can be a helpful way to assess your project.
• There are several sites for hosting documentation that automatically update from your version control repo; we use ReadTheDocs.
• Targeting code to test is easily done by first looking for code that is not executed by your tests, using code coverage.
• The Bus factor is a measure of how well documented your various processes are.
• The paper Best practices for scientific computing is a good overview of things to think about.
• A good overview of our rationale for and experience with adopting these techniques is here.
• We continually self-assess the value of our development process and modify it accordingly; see, for example, some recent modifications.

--titus