Source Control Best Practices for Non-Developer Professionals

Git and git-enabled collaborative platforms like GitHub, GitLab and Bitbucket have revolutionized the software world. Yet there is still an enormous gap between the way source control management is practiced by software development professionals and by communities where programming and code writing are not the primary focus of one's work. The medical research community one such example. Researchers in this community often create various scripts and data processing algorithms as a means to aid research in producing some result or outcome. At the risk of painting with too broad a brush, I imagine that some of these researchers have neither the time nor the desire to stay up to date with the latest-and-greatest methods of managing code. Why would they? Their focus is on medical research. Adhering to the rapidly changing standards of modern day software development is likely not at the top of the priority list; but the cost of not doing so can result in inefficiencies, technical debt and overhead.

So how can non-developer communities get up to speed with source control best practices without dedicating what little time they have to learning it? By mimicking the pros! After years of managing development and professional developer teams, I can sum up what I know to work well in a few short bullet points. I present S.T.R.E.A.M.S:

• Safe: leverage git tags and version numbers to easily undo bad changes and revert to a previously known-good state.
• Transparent: make it easy to see who is working on what, where, when and why with extensions like the beautiful Git Graph for VSCode.
• Readable: produce straightforward development history and logs. Refrain from using a git log as a personal development diary by writing commit messages in the imperative mood.
• Efficient: merge code regularly and often so that releases are less painful and conflict-free.
• Agreed-upon structure: have a single source-of-truth that is never directly committed to, only merged to. Many software teams use their master branch for this, which is managed by a dedicated release engineer who reviews other developers' pull requests.
• Modernized: adopt a workflow like git flow (or the even more modern GitHub flow) to ensure your project will be readable and understandable years into the future... and likely by developers other than yourself.
• Scalable: the model that allows both single developers and large development teams to operate efficiently is based on the understanding that git branching is cheap. Every new feature or code change should get its own branch or stream.

Practice S.T.R.E.A.M.S. with consistency and discipline, and the chore of source code control will no longer be an obstruction, but a necessary tool you can't afford to live without!