+++*

Symbolic Forest

A homage to loading screens.

Blog : Posts tagged with ‘git’

Cross-pollination

Or, some ideas for tracking ideas

A few days ago, I mentioned in passing that there I have lots of ideas for topics to write about on here, and the backlog of ideas is slowly building up. What I didn’t say was: how I track the backlog and remember all those ideas; instead, I thought to myself, that would make an interesting post for another day. “Backlog” isn’t meant to be derogatory, by the way. I see it as a good healthy thing, that I have lots of ideas that I haven’t as yet have had the time or energy or inclination to turn into words yet. Better that than a dearth of things I want to talk about, after all; that’s what would make this site slowly dry up and wither.

The Plain People Of The Internet: That and there not being any readers.

I don’t mind too much if there aren’t any readers. If I cared about readers I’d be cross-promoting this everywhere, doing complex deals and joint projects and promoting myself as the exciting new face of self-published diarising. I don’t, though, because the point of this is the writing, not the reading. But that’s by-the-by too really.

It’s very easy to get into the situation where ideas do just flit away on the wind as soon as they come along, and the spark of inspiration never gets turned into a post on here. Write your ideas down, is the standard piece of advice, but that means having something to write with, something to write on, and somewhere to collate and collect all of your scribbled notes. Working in software development, though, there are a few closely-related solved problems, so when I restarted this blog last summer I decided I was going to use the skills and tools I know from the day job to help me plan and track my writing on here. There are two key related tools that I’ve been using to help, which any software people reading this really should know about: version control and issue tracking.* If you are a software person, and you think the next paragraph is teaching you to suck eggs a little bit, then just remember that there are always people in the world who don’t know this stuff. Nobody is born with an innate knowledge of project management.

Version control is, very simply, the idea of keeping an archive of your working files that preserves their state over time, at least at the intervals you choose. It has a long history; the concept has been around probably longer than computers themselves. The leading system for it at the moment is called “git”, and was created by Linus Torvalds in order to help with development of his “Linux” operating system.** It effectively takes snapshots of all the files in a given folder at a point in time, and you can reset your “working copy” of the files to any snapshot whenever you want to. Moreover, each snapshot (or “commit” in the jargon) has a record of its parentage, and this ties commits together in a way that makes the folder’s history more than just one-dimensional. The chain of commits starting at a particular recent one and reaching back through the sequence of ancestral commits is called a “branch”; your archive can contain any number of named branches in parallel, and you can switch between branches whenever you want too. Not all developers really understand how to use branches properly, but if you do, they are a very powerful tool to help you organise disparate strands of work.

Git was originally designed to be a highly decentralised system without any single copy of the archive holding the privileged position of being the main primary copy. Most developers, however, don’t actually use it like that. A number of companies and organisations have sprung up to offer Git hosting services, and most development teams use one of these hosting services to host the primary copy of their Git data and use it as a centralised exchange point to share their code. That isn’t an issue for me writing this website, but these hosting services also offer additional services which are very useful: particularly, in the context of this post, ticketing systems. These are basically databases that let you create a “ticket”, generally some sort of work item such as a bug, a new feature or a task to be completed, and then let you track the progress of each one. The really fancy systems are so customisable you can completely shoot yourself in the foot designing over-complicated workflows, building reports, and adding custom data fields to each type of ticket, but I don’t care about any of that. The important thing here is that I can create a ticket, and I can access the “create ticket” function from anywhere through my phone. Whenever an idea for a new post comes along, I can immediately create a ticket with a brief description or title in it; then when I sit down to write something, I have a whole list of ideas I’ve had on the screen in front of me. Nothing gets forgotten, and all the ideas are there for me to come back to eventually, unless I didn’t put in enough of a description for it to make any sense.

When I start work on a post, I do exactly what I’d do when working on a piece of code. I read the ticket and click the button to flag it as in progress. I go to Git, make sure I’m at the tip of the “main” branch (as this reflects what’s currently on the website), and create a new branch with the ticket number in its name. I go into the site’s content code and create the new post, and when I’m happy with what I’ve written I create a commit with the new article in. Then, my Git hosting site has tools to help me check over what I’ve just done before folding those changes into the “main” branch. If I really wanted to, I could set up “continuous integration” code that would automatically push those changes out to the website as soon as they are folded into the main branch; although I’d use that for a software project, for this site I prefer to keep that process manual. When the changes have been made and the whole thing has been published, I mark the ticket as “closed”, and it disappears from my ticket backlog.

This sort of system isn’t for everyone, and it might not work for you, but I find it invaluable to keep track of what I’ve been thinking and what I’ve been planning. I find it’s fairly lightweight—it helps that I need to be comfortable with the tools anyway—but I understand not everyone is likely to agree. The hardest part, at least at first, is the discipline. Thinking to myself “better create a ticket for that” when an idea pops into my head, rather than just letting the idea float away again. Then again, that discipline is just as important if you rely on writing all your ideas down on paper; and the benefit of the technology is being able to easily file them all once you’ve done that. If anyone reading this is a non-tech person who has adopted these type of tools for non-tech activities like writing or indeed anything else, I’d love to know, and I’d love to know how much of a success it has been for you. For me, this is one big thing that helps me write, because it turns a lot of the administrative aspect of the writing process into something that is purely mechanical. For you, it might be different—but I’d love to know what you think.

* To be honest, there are a few software dev workshops that don’t use one or the other of those tools, even though they almost certainly should. They’re not new, and they make your life a lot easier. Even in top global businesses there are teams here and there who refuse to use version control, or more commonly, don’t really understand how to use it properly. It would be unprofessional of me to name and shame, but all I’ll say is, you would be surprised.

** This is not the place for a debate over whether Linux is an operating system or not.

Inconsistency

In which different tools behave in different ways

One of those days when everything seemed to go wrong at work this afternoon. Partly because of things I broke, partly because of things that other people had messed up before I got there, partly because of things that seemed to go wrong entirely by themselves.

For example - warning, dull technical paragraph ahead - I hadn’t realised that Visual Studio can cope remarkably well with slightly-corrupt solution files and will happily skip over and ignore the errors; but other tools such as MSBuild will throw the whole file out, curl up and cry into their beer. Visual Studio, whilst ignoring the error, also won’t fix it. Therefore, when git is a git and accidentally corrupts a solution file in a merge, you will have no problems at all on a local build, but mysterious and hard-to-fix total failures happen whenever you try to build on the build server.

Update, September 8th 2020: At some point I will write a proper blog post about what happened here, how to spot it is going to happen, and how to fix it, because although MSBuild is going away now we are in the .NET Core world there are still plenty of people out there using .NET Framework, and they still occasionally face this problem.