Git and the zombies

[liv]

Three years since I touched DW dev, so I'm rusty as you could imagine. I decided to start with a simple colour theme, because at least I know S2 meaning that it would be a way of doing hello world and getting used to the workflow for submitting patches. I grabbed the top entry from dreamscapes, which happened to be four themes by rising. rising has excellent colour sense and enough experience with DW that his themes are generally almost ready to go with minimal tweaking, so that made it an easy starter bug for me.

As it happens, several things about the environment have changed over my long hiatus. The S2 layer editor has been tweaked so it's less user-hostile (I always test code in the layer editor first before I start changing theme files). DW's file structure has been moved around and rationalized a bit so it's more logical and easier to find the file to work with. The Wiki has ridiculously better documentation than what I was working with when I first started, including detailed style guidance so that code committed by different people, even newbies, will have the same structure, yay.

And... we have migrated from Mercurial to Git. I know a lot of people found it hard to adapt, so the fact I've forgotten everything I ever knew about submitting patches probably actually stood me in good stead. Getting set up was pretty easy; I went into #dreamwidth IRC to ask if I should try to revive my old Dreamhack or start afresh, and sophie happened to be online so she set me up with a new 'hack right away. I followed Dreamhack Getting Started from the Wiki, and it was pretty smooth sailing, apart from a very minor issue about config.pl. Viz, the documentation was slightly out of date and the inheritance pattern between the master file and the local one was a bit off. But people in IRC quickly fixed that for me and updated the Wiki page on the fly, so that was fine.

Then I turned to Getting started on Windows. In fact I was able to skip most of the first half of the page as I already had a Bugzilla account, a CLA, and all the software from last time I was active in development. The only new thing was creating a GitHub account and forking the DW code. And that was delightfully straightforward! Then I followed the links from the Getting Started page to create bash scripts for updating. Again, straightforward and I refreshed my memory on how to use WinSCP to modify files on my Dreamhack.

So from here on in, Make changes to your local code and Adding a new color theme become my Bible. I keep referring back to them at every step, and being impressed at how helpful and clear they are!

I create a Bugzilla bug. Easy for me, I'm familiar with Bugzilla. I notice 'zilla has been modernized slightly since I last poked it, but only in ways that make it easier to use, not harder. Then I have to make a Git branch. That seems to work; being over-cautious because I'm still a bit scared of Git, I devote a whole branch to just one theme, Evening.

Rather than go straight to modifying the files, I work in the web-based S2 editor on my Dreamhack. Mainly because I like having the preliminary check of clicking compile and getting "No errors" and then going direct to my journal and seeing if it looks right, without having to mess around updating databases. And because it keeps the worst stages of my initial, error-filled attempts out of my dev environment and the code that I actually ask people to review. Yes, I have issues about doing stuff badly; volunteering for DW and being admittedly a very very tiny little babydev is part of what I'm doing to try to get round that.

I fairly quickly manage to get a theme layer that works, that looks identical to rising's submission to dreamscapes, and fits the style guide in Adding a new color theme. Then I modify Patsy/themes.s2 using WinSCP plus Notepad++, and following the instructions in How to patch styles and themes to find the relevant file. Update the database on my Dreamhack (dwdb), check that the Evening theme is now available as a selectable style from the customize wizard and listed in the layers directory, and there's my first little patchling.

I'm generally hanging out in IRC while I code, and people are being encouraging and don't seem to mind my habit of thinking aloud. I get a bit of reassurance that (unlike the bad old days) you can actually make a complete new colour theme by altering one file only, and some suggestions for testing said colour theme (eg setting the browser background colour to something other than the default and checking it doesn't show through; you'd be surprised how many quite major pro sites fail this test now I've changed this setting!)

Time for my first interaction with Git. I initially didn't quite understand what was supposed to happen in between git add, git commit and git push, but the answer is that if you're not being excessively cautious due to trying everything for the first time, you can add several files to the same commit, one at a time if need be. And you can test the locally committed files before pushing them to GitHub. Once I'd had that explained to me, I was able to make my first pull request. I was a bit confused about the relationship between a pull request in the new system and a patch in the old, Mercurial-based system, but IRC people helpfully explained all.

Then I repeated the whole process to implement rising's Hollow Silence theme, with a bit less stopping to ask questions at every single step. Then the same for Today I'm Happy. So, three teeny twig-like branches on Git, each with a single altered file. This is about the point where I start to like Git, because I was a bit confused about what would happen with trying to compare my new theme to the original parent version, or the version after I'd added the previous themes. And Git makes this just magically work; with Mercurial I'd have had to think it through carefully at each stage and probably messed it up!

Then, after I went offline, afuna came and reviewed my pull requests. She found some minor style errors and very gently explained to me what I needed to fix. So I revised the relevant files and updated the branches and it was generally very plausible. However, at some point in this process I did something wrong, I think it was to do with forgetting to switch to the right branch before I made a change, I really don't know. But as a result of that, every time I did anything I ended up with this commit in my branches. That isn't a real commit at all, it's just whatever happened to be the latest change to the repository at the time I made the error.

So the first time it happened, I went in IRC and mark and others helped me clean up my branch with that incorrect commit in it. And we made a new branch and used Git magic to cherrypick the wanted commits and leave behind the weird messed up one. However, when I went to look at GitHub again the messed up commit was right there in the newly created branch after all. Then I got stressed about having messed up, and also busy, so I left it alone for a week or so. I did a bit of trying to troubleshoot, with the help of sophie and others in IRC, trying to figure out what I had done to put that commit into both the original Hollow Silence branch and the new version I made with mark's help. This ended up with updating the dwu script a bit, and some even more careful checks for me to make to really really make sure I wasn't in the wrong branch at any point, but we didn't really track down the problem.

When I came back, I decided to start again with a completely new thing, namely implementing the sole Leftovers theme from rising's post. And it was all fine, went through the process with no problems, until I made the pull request on GitHub and bam, the zombie commit appeared again in my newly created branch that had nothing to do with the previous problem I'd had. So I went back to IRC and mark took a look at the situation. We still couldn't figure out what exactly I had done wrong to cause this zombie commit to keep showing up all the time, but mark was able to fix it and make sure that my repository was clean and I could safely create new branches.

Oh, and in between this, I learned how to make preview images, a step I've always struggled with before in making S2 themes. My main issue is that the only image manipulation software I have is Photoshop, which is a bit overkill for just resizing things down to 150x114. Plus I can't start Photoshop on my computer without a clean restart, which is very annoying if I'm in the middle of developing and have a browser with multiple tabs and PuTTY and WinSCP and an IRC client (Pidgin) open. Also I didn't really know how to take a screenshot of the actual screen area, not the whole desktop including all the toolbars and unwanted gubbins, and again, cropping all that out of the image is faffy. So I installed a Firefox extension, Fireshot, as instructed in the Wiki, and played around until I had worked out that the correct plan is to open my journal in a new window, use F11 to fullsize it, and then take the screenshot with Fireshot, giving me a .png with the appropriate aspect ratio. The second thing that happened was that momijizukamori and sophie installed ImageMagick into the Dreamhacks, meaning that I could resize images actually on my hack by simply invoking a script, much easier than faffing around with Photoshop. The thing I need to be careful of is that I have to add the file to git, not the whole folder with all the preview images in it, because Momiji's script resizes all the files, even the ones that are already the right size and I don't want them to show up as changed files in my commits.

The thing that was frustrating about this was not being able to work out what I'd done wrong! I'm not worried about making a mistake, that's obviously going to happen when I'm learning the system for the first time. What I found difficult was that the thing I did wrong, whatever it was, was untraceable, and most especially that it was putting the zombie commit into all my branches, even though I was being ultra, ultra careful to do everything right when I created the branches. However, everybody in IRC was incredibly supportive and helpful, so I'm not going to give up trying to learn version control because of that set-back.