Forem: Tech Around And Find Out

Using `git bisect` to figure out when brokenness was introduced

Tech Around And Find Out — Mon, 03 Jul 2023 15:23:47 +0000

One fine day, I did a fresh installation of Drupal 8, and came across a bit of ugliness: an ugly grey border on the home page, caused by an empty div being inserted into the page:

My last fresh install was about a week prior and didn't have this problem. I didn't relish the idea of going through all of the commits since then one-by-one to figure out where this bug was introduced.

Enter the git bisect command!

The git bisect command works by performing a "binary" search between one state of the code and the other in order to find, by process of elimination, where a given problem was introduced. It's quick, it's easy, and by golly, it just works!

Here's how to use git bisect, step-by-step!

Step 1: Find a commit where things were working.

Have a look through the git log for a commit from around the time you know things were last working, such as fd0a623f478e335794e09.

Confirm that this commit actually works ok by switching your checkout to it instead:

(Tip: you only need to reference the first 5-6 characters of the commit hash; you don't need the entire thing... Git is smart and will figure it out!)

$ git checkout fd0a623f

Note: checking out 'fd0a623f'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

git checkout -b new_branch_name

HEAD is now at fd0a623 - Patch #1201024 by pillarsdotnet: drupal_realpath() should describe when it should be used.

Now refresh your Drupal site in your browser. Yay! No more ugly border. So we know that this version of the code, at least, was working okay. Progress!

**Step 2: Find a commit where things are not working.**

Next, we need to know the current commit hash, where things are not working so well. That would be 256d85044583970a2d39e.

Confirm this by doing:

$ git checkout 256d85
Previous HEAD position was fd0a623... - Patch #1201024 by pillarsdotnet: drupal_realpath() should describe when it should be used.
HEAD is now at 256d850... Issue #1011614 by catch: Fixed Theme registry can grow too large for MySQL max_allowed_packet() and memcache default slab size.

...and refreshing the page again. That ugly border is back again. Ick!

Step 3 - N: Use git bisect to find the problem commit.

Great. So we know where it was working, and we know where it isn't anymore. Time for some fun!

To begin, we need to start git bisect and then give it the "known good" place, and the "known bad" place.

$ git bisect start
$ git bisect good fd0a623
$ git bisect bad 256d850
Bisecting: 28 revisions left to test after this (roughly 5 steps)
[68c0c8c6359961cbef832398c4ddab0fe2f17083] Issue #1238258 by kiamlaluno, izmeez: Change 'Track page visits' to 'Page visits'.

Git bisect looked at all of the commits between fd0a623 and 256d850, picked the middle one, and switched the current checkout to that instead.

Now, we need to figure out if the code in commit 68c0c8c has the same issue or not. Reload the page. Hey, the ugly border is gone again!

Tell Git about the good news, and it will start the next search, this time at the halfway point between commit 68c0c8c (new known good) and 256d850 (known bad):

$ git bisect good
Bisecting: 14 revisions left to test after this (roughly 4 steps)
[03b443e8f5043b6e8c3a743ad01a3db9d663ad3c] Issue #1123092 by michaellenahan, varunarora: Fixed user-profile.tpl.php doc has confusing/misleading first paragraph.

Refresh the page. Ewww. Border's back again. That's no good. However, we did manage to find a new "known bad" state. Let's tell Git about it so it can give us a new version to try:

$ git bisect bad
Bisecting: 6 revisions left to test after this (roughly 3 steps)
[e217c4ef1bf06ad75bf6124b9af520195f212001] Issue #1291458 by arithmetric: Fixed Database::getConnection mentions short-lived fixed bug and shouldn't.

You know the drill now. Reload. Border gone. Bisect good!

$ git bisect good
Bisecting: 3 revisions left to test after this (roughly 2 steps)
[08b9bd41723a0a23687c59033c15d66c1840b4f3] Issue #918808 by moshe weitzman, Damien Tournoud, dww: Standardize block cache as a drupal_render() #cache.

Reload. Border's back. BAD!

$ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 1 step)
[9763ca906a6229125dfbe1b56956405457d55892] Issue #1290512 by droplet: Fixed Seven: remove duplicated css.

One last time, reload. Border's gone. GOOD!

$ git bisect good
08b9bd41723a0a23687c59033c15d66c1840b4f3 is the first bad commit
commit 08b9bd41723a0a23687c59033c15d66c1840b4f3
Author: Nathaniel
Date: Thu Sep 29 12:29:59 2011 +0900

Issue #918808 by moshe weitzman, Damien Tournoud, dww: Standardize block cache as a drupal_render() #cache.

:040000 040000 493cba4b1f84c0e907a37f5f4e40d3576bb84785 7763c1bb6f7e4e7b1296863b5df945f5b1760f67 M modules

BAM! By process of elimination, we've just found our problem commit! It was from pesky old issue #918808. Time to update the issue with a pointer to the bug it introduced (and vice-versa).

Step 4: Get back to a working state.

Once you're all finished up, run these commands to end your git bisect session and get back to the normal branch:

$ git bisect reset
Previous HEAD position was 9763ca9... Issue #1290512 by droplet: Fixed Seven: remove duplicated css.
HEAD is now at 256d850... Issue #1011614 by catch: Fixed Theme registry can grow too large for MySQL max_allowed_packet() and memcache default slab size.

$ git checkout 8.0.x

Switched to branch '8.0.x'

Now you're back in business!

Awww, yeah!

We've successfully deduced where a problem was introduced in about 3 minutes. Sifting through commit logs and trying to revert patches on an ad-hoc basis can take 10 times that or more. Let's say it together now, Git bisect rules!! :D

Using iCalendar for semi-predictable but oddball events

Tech Around And Find Out — Sat, 06 Nov 2021 08:49:06 +0000

(RFC reading for fun and pragmatism!)

Background

My girlfriend is a nurse, and around these parts that means she works shift work. Her schedule is a block of shifts (sometimes day shifts, sometimes evening shifts) followed by a block of days off (which also varies as to the number of days), and the entire schedule itself repeats every so many weeks. Basically, picture something like this:

..and repeat.

While there is a pattern to it, it essentially means that without access to a copy of her schedule readily at hand, it is literally impossible to know if we are free on some random day next month. So obviously, I want an electronic version at the ready for these types of inquiries.

Unfortunately, it is also incredibly tedious to enter all of these shifts one by one, by hand, into something like Google Calendar, because it requires manually creating dozens of events (“repeats every other Monday” unfortunately does not cut it here :P), and on each of them, manually selecting “Repeats,” manually selecting “Custom…”, manually selecting “every X weeks”, all without introducing any errors. Ugh.

Fortunately, here to save the day… the iCalendar specification!

What is the iCalendar specification?

The iCalendar specification (as in RFC 5545, not to be confused with good ol’ iCal, now known as Apple’s Calendar app) is a “data format for representing and exchanging calendaring and scheduling information such as events, to-dos, journal entries, and free/busy information, independent of any particular calendar service or protocol.”

Basically, it’s a list of rules about how to describe events in computer-friendly language, and if you follow those rules, users can import your events consistently in whatever various calendaring programs they might be using. Glancing through the specification, you’ll see it talks about how to specify all kinds of features you may have seen in various calendaring apps, such as:

Specify a location
Specify a time zone
Repeat an event with a certain frequency
Note whether someone’s an optional or required attendee
Denote whether it shows up as busy or free time on someone’s calendar
Send an alert a few minutes before an event happens

...and much, much more.

If you’ve ever received an email with a .ics file attached, and when you click it you’re prompted to add an event to your calendar, such as below… Congratulations! You officially have experience with iCalendar! :D

Let’s talk about what iCalendar looks like under the hood.

The Basics of iCalendar

The “simplest thing that can possibly work” in terms of iCalendar is a text file, with an .ics extension, that contains the following properties:

BEGIN:VCALENDAR … END:VCALENDAR: (required) Marks the beginning and end of the iCalendar object as a whole (similar to how … wraps around a web page).
VERSION: (required) The version number of the specification required (generally, “2.0” unless you’re feeling super retro).
PRODID: (required) A unique identifier for the product that created the iCalendar object. Some real-world examples are “-//Google Inc//Google Calendar 70.9054//EN” for Google Calendar and “-//Apple Inc.//Mac OS X 10.14.6//EN” for Apple Calendar.
BEGIN:VEVENT … BEGIN:VEVENT: One or more of these pairings mark the beginning and end of an event definition.
UID: (required) A unique identifier for the event. [buncha-random-chars] and [buncha-random-chars]@[yourdomain.com] are both common patterns.
DTSTAMP: (required) The date/time that the event was created (not to be confused with when it starts, which is the next one).
DTSTART … DTEND: When the event starts and ends.

Here’s a simple example tying all of that together:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp//Example Calendar App 1.0//EN
BEGIN:VEVENT
UID:20210310T001345Z-0242ac130003@example.com
DTSTAMP:20210310T001345Z
DTSTART:19991231T235959
DTEND:20000101T000000
SUMMARY:Party like it’s 1999!
END:VEVENT
END:VCALENDAR

If you save this as “y2k.ics” and import it, you should see a new event appear at the very tail end 1999 that lasts from 11:59:59PM on December 31, 1999 until midnight on January 1, 2020!

How to specify a date/time?

The RFC gets into this at length, but the basic gist is:

If it’s a date only, it’s specified in the format of YYYYMMDD.
If it’s a date and time, it’s specified in the format of YYYYMMDDTHHMMSS (with HH in 24-hour time). If it’s a UTC time (see below) it also has a Z at the end.

There are three different ways to specify a date and time such as 11:59:59PM on December 31, 1999:

Date with local time: Used when you want an event to be at the same time, regardless of a person’s location.

    DTSTART:19991231T235959

Date with UTC time: Used when you want an event to be at an absolute time across all geographic locations, and disregarding Daylight Savings Time. (Note: DTSTAMP is always in this format.)

     DTSTART:19991231T235959Z

Date with local time and timezone reference: A combination of both; it pegs to a specific time, but within a given time zone, so it takes into consideration things like Daylight Savings Time.

     DTSTART;TZID=America/Vancouver:19991231T235959

In the above example, we went with the “date with local time” format so that the event would be at the same time regardless of location, since exactly when the “last minute of 1999” is differs across the globe. But for tracking shift schedules, “Date with local time and timezone reference” makes more sense, because if I fly to Europe for work, I don’t want the start times to shift by several hours.

Nope, that semi-colon after DTSTART in the third example is not a typo. “Property parameters” such as TZID are passed in with a semicolon rather than a colon. (See List and Field Separators) This will also come into play with...

Repeating Events

Ok, so we already have enough information to create each shift schedule the first time, but note that it repeats every X weeks. How do we handle that?

Enter Recurrence Rules (RRULE)! This property defines a rule or repeating pattern for recurring events. Here are just a few of the options that it supports:

FREQ: How often the event occurs. Some examples are WEEKLY, DAILY, and even SECONDLY.
INTERVAL: How many FREQs should there be in between events?
COUNT: Repeat the event X times. (Useful if you have a class that runs for 4 weeks, for example)
UNTIL: Alternatively, this will repeat the event until a certain date.
BYDAY: Allows you to say something only happens on certain days of the week.

The RFC has all sorts of examples.

Putting it All Together

For our purposes, we need events that:

Use a Date with local time and timezone reference because I travel frequently (in non-COVID times) and I want the events to be shown at the proper start/end times regardless of where I am in the world.
Have a FREQ of WEEKLY and an INTERVAL of 8 since the schedule repeats every 8 weeks.
And an UNTIL date of 12/31/2021 because the schedule gets reset every calendar year, and next year will be something different! (Hance my very strong desire to write this process down. ;))

Put it all together, and you get:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Webchick Inc//Webchick’s Crappy Bash Script 1.0//EN
BEGIN:VEVENT
UID:3231CB09-1E10-4910-BB24-B358629890B7
DTSTAMP:20210314T090733Z
SUMMARY:Day Shift
DTSTART;TZID=America/Vancouver:20210111T080000
DTEND;TZID=America/Vancouver:20210111T180000
RRULE:FREQ=WEEKLY;INTERVAL=8;UNTIL=20211231
END:VEVENT

... (repeat x many more events) ...

BEGIN:VEVENT
UID:F20376E5-FA0F-429D-AB1F-3F0155EE10BA
DTSTAMP:20210314T090734Z
SUMMARY:Evening Shift
DTSTART;TZID=America/Vancouver:20210208T173000
DTEND;TZID=America/Vancouver:20210208T233000
RRULE:FREQ=WEEKLY;INTERVAL=8;UNTIL=20211231
END:VEVENT

... (repeat x many more events) ...

END:VCALENDAR

And when imported into Apple Calendar:

And there you have it!

So. The next time you get one of those .ics files, try popping it open in a text editor and see how much of it makes sense now!

PS: If you want to see the bash script I used to generate this, it’s at https://github.com/webchick/shiftycal. If you want to go it alone, this handy validator is your friend!

(Cover image: "iCal icon replacement" by bertop is licensed under CC BY-NC-SA 2.0)