Well, it’s happened again. They’ve gone and renamed Comiskey Park to something else. And I feel about the same way I did back in 2004, when the last name change happened.

I lived a few blocks from the park at that time, as opposed to the few thousand I do now, but it still upsets me. Whatever happens, it’ll always be Comiskey Park to me.

I have a tradition on Thanksgiving: I listen to Arlo Guthrie’s classic Alice’s Restaurant Massacre; all 18 minutes and 37 seconds of it. I don’t remember exactly where I picked up this tradition, but it feels distinctly mine since it’s not something that my family did growing up.

Anyway, I found out yesterday that the song is available on Spotify in its full-length glory. So kick back, close your eyes for 20 minutes, and enjoy.

Engineer is a side project for me right now. That means that while I am actively working on Engineer pretty regularly, releases themselves are not necessarily regular. I’ve adopted a repository/branch structure that’s influenced by git flow, so my main development branch is not master, it’s dev.

• master: The most recent released version of the code
• dev: The in-development version of the code

Up until Engineer v0.5.0, when you went to GitHub, you saw master by default.

When you go to GitHub, I want you to see the latest in-development version. The reason is pretty simple: Since official releases are fairly slow, but I actually make changes fairly often, I want to make sure that activity is shown on the GitHub homepage – via the ‘x days ago’ text that shows up on the far right of the code listing. My hypothesis is that people make some judgements based on the activity level of project. If people are searching for a static site generator, and they come across Engineer, I don’t want them to think that the project is abandoned and simply leave. If my default branch shown in GitHub is master, then it looks as though the project isn’t under active development at first glance, which clearly isn’t what I want. Thus, I want GitHub to display the dev branch by default, which is easy enough to change in the repository settings. I made this change along with the release of Engineer v0.5.0, so now when you go to the repository on GitHub, you’ll see the dev branch by default.

There’s still a problem, though, related to the fact that I host Engineer’s public documentation on Read the Docs (RTD). Imagine someone finds my project on GitHub, likes what they see, and installs the release version using pip:

pip install engineer

Seems to be the natural thing to do, right? If they click the link in Engineer’s README to visit the docs at RTD, then I want them to go to the version of the docs that corresponds to the version they just installed – the most recent released version.

Now this is also relatively easy to do. RTD actually has some smarts around multiple versions of documentation. RTD offers a few different settings that are relevant to my goals.

First, there is a baked in ‘version’ identifier called latest which is intended to point to the most recent version of your docs:

In the normal case, the latest version will always point to the most up to date development code. If you develop on a branch that is different than the default for your VCS, you should set the Default Branch to that branch.

Of course, in my case, development is done on the dev branch, so I want latest to point to that branch. Fortunately that’s easy to change, as the second sentence above alludes to. In the Advanced Settings section of the RTD dashboard, you’ll find a Default branch setting, in which I entered dev. Great; now latest points to dev.

The second setting of relevance in RTD is the default version. This controls what version of your docs / redirects to. By default this will be latest, but since I want / to always redirect to the most recent released version of Engineer, I changed this to master. Cool; now / simply redirects to the version of my docs from the master branch, which will always be the most recent released version.

There is, of course, still a problem. Ideally, I would like links that people follow to go to the version of the documentation that matches the version of the code they’re coming from and vice-versa. In other words, I would like the documentation link from the README file in the master branch to go to https://engineer.readthedocs.org/en/master/, and the link in the dev branch to go to https://engineer.readthedocs.org/en/latest/.

Unfortunately, that’s not really possible. Sure, I could build some intelligent redirector or something that would look at the referrer URL and redirect to the appropriate docs version, but that’s not something I want to build anytime soon. The best I can do is provide some notes in the documentation itself telling people that they may be looking for a version of documentation that is different from what they’re seeing. It’s not quite ideal from my perspective, but I think it helps.

So bottom line, this is what I’ve wound up with:

• If you go directly to https://engineer.readthedocs.org/, you’ll get the latest released version of the docs, which will correspond to what most people will install using pip.
• If you visit the GitHub repo, you’ll see the most recent in-development version of the code. The README links to https://engineer.readthedocs.org/, which as I mentioned earlier will redirect to the released version of the docs.
• The docs themselves contain notes redirecting people to https://engineer.readthedocs.org/en/latest/ if they need the most recent version of the docs. RTD itself also contains links to all versions of the docs, but I don’t think most people know that and if they do, it may not be clear which version they want.

Daniel Cook tells you more than you ever needed to know about loot tables. Unless you’re a game designer, of course…