GSoC on Victor Ma

Google Summer of Code final report

Fri, 07 Nov 2025 00:00:00 +0000

For Google Summer of Code 2025, I worked on GNOME Crosswords. GNOME Crosswords is a project that consists of two apps:

Crosswords, a crossword player
Crossword Editor, a crossword editor.

Project summary

I improved GNOME Crossword Editor’s word suggestion algorithm, by re-implementing it as a forward-checking algorithm. Previously, our word suggestion algorithm only considered the constraints imposed by the intersection where the cursor is. This resulted in frequent dead-end word suggestions, which led to user frustration.

To fix this problem, I re-implemented our word suggestion algorithm to consider the constraints imposed by every intersection in the current slot. This significantly reduces the number of dead-end word suggestions and leads to a better user experience.

As part of this project, I also researched the field of constraint satisfaction problems and wrote a report on how we can use the AC-3 algorithm to further improve our word suggestion algorithm in the future.

I also performed a competitive analysis of other crossword editors on the market and wrote a detailed report, to help identify missing features and guide future development.

Word suggestion algorithm improvements

The goal of any crossword editor software is to make it as easy as possible to create a good crossword puzzle. To that end, all crossword editors have a feature called a word suggestion list. This is a dynamic list of words that fit the current slot. It helps the user find words that fit the slots on their grid.

In order to generate the word suggestion list, crossword editors use a word suggestion algorithm. The simplest example of a word suggestion algorithm considers two constraints:

The size of the current slot.
The letters in the current slot.

So for example, if the current slot is C A _ S, then this basic word suggestion algorithm would return all four-letter words that start with CA and end in S—such as CATS or CABS, but not COTS.

The problem

There is a problem with this basic word suggestion algorithm, however. Consider the following grid:

+---+---+---+---+
| | | | Z |
+---+---+---+---+
| | | | E |
+---+---+---+---+
| | | | R |
+---+---+---+---+
| W | O | R | | < current slot
+---+---+---+---+

4-Down begins with ZER, so the only word it can be is ZERO. This constrains the bottom-right cell to the letter O.

4-Across starts with WOR. We know that the bottom-right cell must be O, so that means that 4-Across must be WORO. But WORO is not a word. So, 4-Down and 4-Across are both unfillable, because no letter fits in the bottom-right cell. This means that there are no valid word suggestions for either 4-Across or 4-Down.

Now, suppose that the current slot is 4-Across. The basic algorithm only considers the constraints imposed by the current slot, and so it returns all words that match the pattern W O R _—such as WORD and WORM. But none of these word suggestions actually fit in the slot—they all cause 4-Down to become some nonsensical word.

The problem is that the basic algorithm only looks at the current slot, 4-Across. It does not also look at other slots, like 4-Down. Because of that, the algorithm doesn’t realize that 4-Down causes 4-Across to be unfillable. And so, the algorithm generates incorrect word suggestions.

Our word suggestion algorithm

Our word suggestion algorithm was a bit more advanced than this basic algorithm. Our algorithm considered two constraints:

The constraints imposed by the current slot.
The constraints imposed by the intersecting slot where the cursor is.

This means that our algorithm could actually handle the problematic grid properly if the cursor is on the bottom-right cell. But not if the cursor is on any other cell of 4-Across:

Consequences

All this means that our word suggestion algorithm was prone to generating dead-end words—words that seem to fit a slot, but that actually lead to an unfillable grid.

In the problematic grid example I gave, this unfillability is immediately obvious. The user fills 4-Across with a word like WORM, and they instantly see that this turns 4-Down into ZERM, a nonsense word. That makes this grid not so bad.

The worst cases are the insidious ones, where the fact that a word suggestion leads to an unfillable grid is not obvious at first. This leads to a ton of wasted time and frustration for the user.

My solution

To fix this problem, I re-implemented our word suggestion algorithm to account for the constraints imposed by all the intersecting slots. Now, our word suggestion algorithm correctly handles the problematic grid example:

Our new algorithm doesn’t eliminate dead-end words entirely. After all, it only checks the intersecting slots of the current slot—it does not also check the intersecting slots of the intersecting slots, etc.

However, the constraints imposed by a slot onto the current slot become weaker, the more intersections-removed it is. Consider: in order for a slot that’s two intersections away from the current slot to constrain the current slot, it must first constrain a mutual slot (a slot that intersects both of them) enough for that mutual slot to then constrain the current slot.

Compare that to a slot that is only one intersection away from the current slot. All it has to do is be constrained enough that it limits what letters the intersecting cell can be.

And so, although my changes do not eliminate dead-end words entirely, they do significantly reduce their prevalence, resulting in a much better user experience.

The end

This concludes my Google Summer of Code 2025 project! I give my thanks to Jonathan Blandford for his invaluable mentorship and clear communication throughout the past six months. And I thank the GNOME Foundation for its participation in GSoC and commitment to open source.

This is a test post

Wed, 15 Oct 2025 00:00:00 +0000

Over the past few weeks, I’ve been working on improving some test code that I had written.

Refactoring time!

My first order of business was to refactor the test code. There was a lot of boilerplate, which made it difficult to add new tests, and also created visual clutter.

For example, have a look at this test case:

static void
test_egg_ipuz (void)
{
 g_autoptr (WordList) word_list = NULL;
 IpuzGrid *grid;
 g_autofree IpuzClue *clue = NULL;
 g_autoptr (WordArray) clue_matches = NULL;

 word_list = get_broda_word_list ();
 grid = create_grid (EGG_IPUZ_FILE_PATH);
 clue = get_clue (grid, IPUZ_CLUE_DIRECTION_ACROSS, 2);
 clue_matches = word_list_find_clue_matches (word_list, clue, grid);

 g_assert_cmpint (word_array_len (clue_matches), ==, 3);
 g_assert_cmpstr (word_list_get_indexed_word (word_list,
 word_array_index (clue_matches, 0)),
 ==,
 "EGGS");
 g_assert_cmpstr (
 word_list_get_indexed_word (word_list,
 word_array_index (clue_matches, 1)),
 ==,
 "EGGO");
 g_assert_cmpstr (
 word_list_get_indexed_word (word_list,
 word_array_index (clue_matches, 2)),
 ==,
 "EGGY");
}

That’s an awful lot of code just to say:

Use the EGG_IPUZ_FILE_PATH file.
Run the word_list_find_clue_matches() function on the 2-Across clue.
Assert that the results are ["EGGS", "EGGO", "EGGY"].

And this was repeated in every test case, and needed to be repeated in every new test case I added. So, I knew that I had to refactor my code.

Fixtures and functions

My first step was to extract all of this setup code:

g_autoptr (WordList) word_list = NULL;
IpuzGrid *grid;
g_autofree IpuzClue *clue = NULL;
g_autoptr (WordArray) clue_matches = NULL;

word_list = get_broda_word_list ();
grid = create_grid (EGG_IPUZ_FILE_PATH);
clue = get_clue (grid, IPUZ_CLUE_DIRECTION_ACROSS, 2);
clue_matches = word_list_find_clue_matches (word_list, clue, grid);

To do this, I used a fixture:

typedef struct {
 WordList *word_list;
 IpuzGrid *grid;
} Fixture;

static void fixture_set_up (Fixture *fixture, gconstpointer user_data)
{
 const gchar *ipuz_file_path = (const gchar *) user_data;

 fixture->word_list = get_broda_word_list ();
 fixture->grid = create_grid (ipuz_file_path);
}

static void fixture_tear_down (Fixture *fixture, gconstpointer user_data)
{
 g_object_unref (fixture->word_list);
}

My next step was to extract all of this assertion code:

g_assert_cmpint (word_array_len (clue_matches), ==, 3);
g_assert_cmpstr (word_list_get_indexed_word (word_list,
 word_array_index (clue_matches, 0)),
 ==,
 "EGGS");
g_assert_cmpstr (
 word_list_get_indexed_word (word_list,
 word_array_index (clue_matches, 1)),
 ==,
 "EGGO");
g_assert_cmpstr (
 word_list_get_indexed_word (word_list,
 word_array_index (clue_matches, 2)),
 ==,
 "EGGY");

To do this, I created a new function that runs word_list_find_clue_matches() and asserts that the result equals an expected_words parameter.

static void
test_clue_matches (WordList *word_list,
 IpuzGrid *grid,
 IpuzClueDirection clue_direction,
 guint clue_index,
 const gchar *expected_words[])
{
 const IpuzClue *clue = NULL;
 g_autoptr (WordArray) clue_matches = NULL;
 g_autoptr (WordArray) expected_word_array = NULL;

 clue = get_clue (grid, clue_direction, clue_index);
 clue_matches = word_list_find_clue_matches (word_list, clue, grid);
 expected_word_array = str_array_to_word_array (expected_words, word_list);

 g_assert_true (word_array_equals (clue_matches, expected_word_array));
}

After all that, here’s what my test case looked like:

static void
test_egg_ipuz (Fixture *fixture, gconstpointer user_data)
{
 test_clue_matches (fixture->word_list,
 fixture->grid,
 IPUZ_CLUE_DIRECTION_ACROSS,
 2,
 (const gchar*[]){"EGGS", "EGGO", "EGGY", NULL});
}

Much better!

Macro functions

But as great as that was, I knew that I could take it even further, with macro functions.

I created a macro function to simplify test case definitions:

#define ASSERT_CLUE_MATCHES(DIRECTION, INDEX, ...) \
 test_clue_matches (fixture->word_list, \
 fixture->grid, \
 DIRECTION, \
 INDEX, \
 (const gchar*[]){__VA_ARGS__, NULL})

Now, test_egg_ipuz() looked like this:

static void
test_egg_ipuz (Fixture *fixture, gconstpointer user_data)
{
 ASSERT_CLUE_MATCHES (IPUZ_CLUE_DIRECTION_ACROSS, 2, "EGGS", "EGGO", "EGGY");
}

I also made a macro function for the test case declarations:

#define ADD_IPUZ_TEST(test_name, file_name) \
 g_test_add ("/clue_matches/" #test_name, \
 Fixture, \
 "tests/clue-matches/" #file_name, \
 fixture_set_up, \
 test_name, \
 fixture_tear_down)

Which turned this:

g_test_add ("/clue_matches/test_egg_ipuz",
 Fixture,
 EGG_IPUZ,
 fixture_set_up,
 test_egg_ipuz,
 fixture_tear_down);

Into this:

ADD_IPUZ_TEST (test_egg_ipuz, egg.ipuz);

An unfortunate bug

So, picture this: You’ve just finished refactoring your test code. You add some finishing touches, do a final test run, look over the diff one last time…and everything seems good. So, you open up an MR and start working on other things.

But then, the unthinkable happens—the CI pipeline fails! And apparently, it’s due to a test failure? But you ran your tests locally, and everything worked just fine. (You run them again just to be sure, and yup, they still pass.) And what’s more, it’s only the Flatpak CI tests that failed. The native CI tests succeeded.

So…what, then? What could be the cause of this? I mean, how do you even begin debugging a test failure that only happens in a particular CI job and nowhere else? Well, let’s just try running the CI pipeline again and see what happens. Maybe the problem will go away. Hopefully, the problem goes away.

…

Nope. Still fails.

…

Rats.

Well, I’ll spare you the gory details that it took for me to finally figure this one out. But the cause of the bug was me accidentally freeing an object that I should never have freed.

This meant that the corresponding memory segment could be—but, importantly, did not necessarily have to be—filled with garbage data. And this is why only the Flatpak job’s test run failed…well, at first, anyway. By changing around some of the test cases, I was able to get the native CI tests and local tests to fail. And this is what eventually clued me into the true nature of this bug.

So, after spending the better part of two weeks, here is the fix I ended up with:

@@ -94,7 +94,7 @@ test_clue_matches (WordList *word_list,
 guint clue_index,
 const gchar *expected_words[])
 {
- g_autofree IpuzClue *clue = NULL;
+ const IpuzClue *clue = NULL;
 g_autoptr (WordArray) clue_matches = NULL;
 g_autoptr (WordArray) expected_word_array = NULL;

When is an optimization not optimal?

Thu, 28 Aug 2025 00:00:00 +0000

In the past few weeks, I’ve been working on the MR for my lookahead algorithm. And now, it’s finally merged! There’s still some more work to be done—particularly around the testing code—but the core change is finished, and is live.

Suboptimal code?

While working on my MR, I noticed that one of my functions, word_set_remove_unique (), could be optimized. Here is the function:

void
word_set_remove_unique (WordSet *word_set1, WordSet *word_set2)
{
 g_hash_table_foreach_steal (word_set1, word_not_in_set, word_set2);
}

/* Helper function */
static gboolean word_not_in_set (gpointer key,
 gpointer value,
 gpointer user_data)
{
 WordIndex *word_index = (WordIndex *) key;
 WordSet *word_set = (WordSet *) user_data;
 return !g_hash_table_contains (word_set, word_index);
}

word_set_remove_unique () takes two sets and removes any elements in the first set that don’t exist in the second set. So essentially, it performs a set intersection, in-place, on the first set.

My lookahead function calls word_set_remove_unique () multiple times, in a loop. My lookahead function always passes in the same persisted word set—clue_matches_set—as the first set. The second set changes with each loop iteration. So essentially, my lookahead function uses word_set_remove_unique () to gradually refine clue_matches_set.

Now, importantly, clue_matches_set is sometimes larger than the second word set—potentially several orders of magnitude larger. And because of that, I realized that there was an optimization I could make.

An obvious optimization

See, g_hash_table_foreach_steal () runs the given boolean function on each element of the given hash table, and it removes the element if the function returns TRUE. And my code always passes in word_set1 as the hash table (with word_set2 being passed in as user_data). This means that the boolean function is always run on the elements of word_set1 (clue_matches_set).

But word_set1 is sometimes smaller than word_set2. This means that g_hash_table_foreach_steal () sometimes has to perform this sort of calculation:

WordSet *word_set1; /* Contains 1000 elements. */
WordSet *word_set2; /* Contains 10 elements. */

for (word : word_set1)
 {
 if (!g_hash_table_contains (word_set2, word))
 g_hash_table_remove (word_set1, word);
 }

This is clearly inefficient. The point of word_set_remove_unique () is to calculate the intersection of two sets. It’s only an implementation detail that it does this by removing the elements from the first set.

The function could also work by removing the unique elements from the second set. And in the case where word_set1 is larger than word_set2, that would make more sense. It could be the difference between calling g_hash_table_contains () (and potentially g_hash_table_remove ()) 10 times and calling it 1000 times.

So, I thought, I can optimize word_set_remove_unique () by reimplementing it like this:

Figure out which word set is larger.
Run g_hash_table_foreach_steal () on the larger word set.
If the second set was the larger set, then swap the pointers.

/* Returns whether or not the pointers were swapped. */
gboolean
word_set_remove_unique (WordSet **word_set1_pp, WordSet **word_set2_pp)
{
 WordSet *word_set1_p = *word_set1_pp;
 WordSet *word_set2_p = *word_set2_pp;
 if (g_hash_table_size (word_set1_p) <= g_hash_table_size (word_set2_p))
 {
 g_hash_table_foreach_steal (word_set1_p, word_not_in_set, word_set2_p);
 return FALSE;
 }
 else
 {
 g_hash_table_foreach_steal (word_set2_p, word_not_in_set, word_set1_p);
 *word_set1_pp = word_set2_p;
 *word_set2_pp = word_set1_p;
 return TRUE;
 }
}

Not so obvious?

Well, I made the change, and…it’s actually slower.

We have some profiling code that measures how long each frame takes to render. The output looks like this:

update_all():
 Average time (13.621 ms)
 Longest time (45.903 ms)
 Total iterations (76)
 Total number of iterations longer than one frame (27)
 Total time spent in this function (1035.203f ms)

word_list_find_intersection():
 Average time (0.774 ms)
 Longest time (4.651 ms)
 Total iterations (388)
 Total time spent in this function (300.163f ms)

And when I compared the results of the optimized and unoptimized word_set_remove_unique (), it turned out that the “optimized” version performed either worse or about the same. That just goes to show the value of profiling!

More testing needed

So…that was going to be the blog post. An optimization that turned out to not be so optimal. But in writing this post, I reimplemented the optimization—I lost the original code, because I never committed it—and that is the code that you see. But when I tested this code, it seems like it is performing better than the unoptimized version. So maybe I messed up the implementation last time? In any case, more testing is needed!

It's alive!

Tue, 05 Aug 2025 00:00:00 +0000

In the last two weeks, I’ve been working on my lookahead-based word suggestion algorithm. And it’s finally functional! There’s still a lot more work to be done, but it’s great to see that the original problem I set out to solve is now solved by my new algorithm.

Without my changes

Here’s what the upstream Crosswords Editor looks like, with a problematic grid:

The editor suggests words like WORD and WORM, for the 4-Across slot. But none of the suggestions are valid, because the grid is actually unfillable. This means that there are no possible word suggestions for the grid.

The words that the editor suggests do work for 4-Across. But they do not work for 4-Down. They all cause 4-Down to become a nonsensical word.

The problem here is that the current word suggestion algorithm only looks at the row and column where the cursor is. So it sees 4-Across and 1-Down—but it has no idea about 4-Down. If it could see 4-Down, then it would realize that no word that fits in 4-Across also fits in 4-Down—and it would return an empty word suggestion list.

With my changes

My algorithm fixes the problem by considering every intersecting slot of the current slot. In the example grid, the current slot is 4-Across. So, my algorithm looks at 1-Down, 2-Down, 3-Down, and 4-Down. When it reaches 4-Down, it sees that no letter fits in the empty cell. Every possible letter leads to either 4-Across or 4-Down or both slots to contain an invalid word. So, my algorithm correctly returns an empty list of word suggestions.

My first design doc

Tue, 15 Jul 2025 00:00:00 +0000

In the last two weeks, I investigated some bugs, tested some fonts, and started working on a design doc.

Bugs

I found two more UI-related bugs (1, 2). These are in addition to the ones I mentioned in my last blog post—and they’re all related. They have to do with GTK and sidebars and resizing.

I looked into them briefly, but in the end, my mentor decided that the bugs are complicated enough that he should handle them himself. His fix was to replace all the .ui files with Blueprint files, and then make changes from there to squash all the bugs. The port to Blueprint also makes it much easier to edit the UI in the future.

Font testing

Currently, GNOME Crosswords uses the default GNOME font, Cantarell. But we’ve never really explored the possibility of using other fonts. For example, what would Crosswords look like with a monospace font? Or with a handwriting font? This is what I set out to discover.

To change the font, I used GTK Inspector, combined with this CSS selector, which targets the grid and word suggestions list:

edit-grid, wordlist {
 font-family: FONT;
}

This let me dynamically change the font, without having to recompile each time. I created a document with all the fonts that I tried.

Here’s what Source Code Pro, a monospace font, looks like. It gives a more rigid look—especially for the word suggestion list, where all the letters line up vertically.

And here’s what Annie Use Your Telescope, a handwriting font, looks like. It gives a fun, charming look to the crossword grid—like it’s been filled out by hand. It’s a bit too unconventional to use as the default font, but it would definitely be cool to add as an option that the user can enable.

Design doc

My current task is to improve the word suggestion algorithm for the Crosswords Editor. Last week, I starting working on a design doc that explains my intended change. Here’s a short snippet from the doc, which highlights the problem with our current word suggestion algorithm:

Consider the following grid:
+---+---+---+---+
| | | | Z |
+---+---+---+---+
| | | | E |
+---+---+---+---+
| | | | R |
+---+---+---+---+
| W | O | R | | < current slot
+---+---+---+---+
The 4-Down slot begins with ZER, so the only word it can be is ZERO. This means that the cell in the bottom-right corner must be the letter O.

But 4-Across starts with WOR. And WORO is not a word. So the bottom-right corner cannot actually be the letter O. This means that the slot is unfillable.

If the cursor is on the bottom right cell, then our word suggestion algorithm correctly recognizes that the slot is unfillable and returns an empty list.

But suppose the cursor is on one of the other cells in 4-Across. Then, the algorithm has no idea about 4-Down and the constraint it imposes. So, the algorithm returns all words that match the filter WOR?, like WORD and WORM—even though they do not actually fit the slot.

CSPs

In the process of writing the doc, I came across the concept of a constraint satisfaction problem (CSP), and the related AC-3 algorithm. A CSP is a formalization of a problem that…well…involves satisfying a constraint. And the AC-3 algorithm is an algorithm that’s sometimes used when solving CSPs.

The problem of filling a crossword grid can be formulated as a CSP. And we can use the AC-3 algorithm to generate perfect word suggestion lists for every cell.

This isn’t the approach I will be taking. However, we may decide to implement it in the future. So, I documented the AC-3 approach in my design doc.

Bugs, bugs, and more bugs!

Tue, 01 Jul 2025 00:00:00 +0000

In the last two weeks, I did three things:

Fixed a rebus bug.
Combined the two suggested words lists into one.
Found some more bugs.

The rebus bug

A rebus cell is a cell that contains more than one letter in it. These aren’t too common in crossword puzzles, but they do appear occasionally—and especially so in harder puzzles.

Our word suggestions lists were not working for slots with rebus cells. More specifically, if the cursor was on a cell that’s within letters in rebus - 1 cells to the right of a rebus cell, then an assertion would fail, and the word suggestions list would be empty.

The cause of this bug is that our intersection code (which is what generates the suggested words) was not accounting for rebuses at all! The fix was to modify the intersection code to correctly count the additional letters that a rebus cell contains.

Combine the suggested words lists

The Crosswords editor shows a the words list for both Across and Down, at the same time. This is different from what most other crossword editors do, which is to have a single suggested words list that switches between Across and Down, based on the cursor’s direction.

I think having a single list is better, because it’s visually cleaner, and you don’t have to take a second to find right list. It also so happens that we have a problem with our sidebar jumping, in large part because of the two suggested words lists.

So, we decided that I should combine the two lists into one. To do this, I removed the second list widget and list model, and then I added some code to change the contents of the list model whenever the cursor direction changes.

More bugs!

I only started working on the rebus bug because I was working on the word suggestions bug. And I only started working on that bug because I discovered it while using the Editor. And it’s a similar story with the words lists unification task. I only started working on it because I noticed the sidebar jumping bug.

Now, the plan was that after I fixed those two bugs, I would turn my attention to a bigger task: adding a step of lookahead to our fill algorithm. But alas, as I was fixing the two bugs, I noticed a few more bugs (1, 2, 3). But they shouldn’t take too long, and they ought to be fixed. So I’m going to do that first, and then transition to working on the fill lookahead task.

A strange bug

Mon, 16 Jun 2025 00:00:00 +0000

In the last two weeks, I’ve been trying to fix a strange bug that causes the word suggestions list to have the wrong order sometimes.

For example, suppose you have an empty 3x3 grid. Now suppose that you move your cursor to each of the cells of the 1-Across slot (labelled α, β, and γ).

+---+---+---+
| α | β | γ |
+---+---+---+
| | | |
+---+---+---+
| | | |
+---+---+---+

You should expect the word suggestions list for 1-Across to stay the same, regardless of which cell your cursor is on. After all, all three cells have the same information: that the 1-Across slot is empty, and the intersecting vertical slot of whatever cell we’re on (1-Down, 2-Down, or 3-Down) is also empty.

There are no restrictions whatsoever, so all three cells should show the same word suggestion list: one that includes every three-letter word.

But that’s not what actually happens. In reality, the word suggestions list changes quite dramatically. The order of the list definitely changes. And it looks like there may even be words in one list that doesn’t appear in another. What’s going on here?

Understanding the code

My first step was to understand how the code for the word suggestions list works. I took notes along the way, in order to solidify my understanding. I especially found it useful to create diagrams for the word list resource (a pre-compiled resource that the code uses):

By the end of the first week, I had a good idea of how the word-suggestions-list code works. The next step was to figure out the cause of the bug and how to fix it.

Investigating the bug

After doing some testing, I realized that the seemingly random orderings of the lists are not so random after all! The lists are actually all in alphabetical order—but based on the letter that corresponds to the cell, not necessarily the first letter.

What I mean is this:

The word suggestions list for cell α is sorted alphabetically by the first letter of the words. (This is normal alphabetical order.) For example:
```
ALE, AXE, BAY, BOA, CAB
```
The word suggestions list for cell β is sorted alphabetically by the second letter of the words. For example:
```
CAB, BAY, ALE, BOA, AXE
```
The word suggestions list for cell γ is sorted alphabetically by the third letter of the words. For example:
```
BOA, CAB, ALE, AXE, BAY
```

Fixing the bug

The cause of the bug is quite simple: The function that generates the word suggestions list does not sort the list before it returns it. So the order of the list is whatever order the function added the words in. And because of how our implementation works, that order happens to be alphabetical, based on the letter that corresponds to the cell.

The fix for the bug is also quite simple—at least theoretically. All we need to do is sort the list before we return it. But in reality, this fix runs into some other problems that need to be addressed. Those problems are what I’m going to work on this week.

Coding begins!

Mon, 02 Jun 2025 00:00:00 +0000

Today marks the end of the community bonding period, and the start of the coding period, of GSoC.

In the last two weeks, I’ve been looking into other crossword editors that are on the market, in order to see what features they have that we should implement.

I found the process enlightening. It was interesting to try so many different versions of the same product. The UIs differ quite dramatically, the same feature may be implemented differently in each editor, and some features only exist in a few or even a single editor.

Some editors of note:

Ingrid is the editor I liked the most. It’s got a really nice UI, and it has all the important features, without any extraneous ones.
Exet has a lot of word transformation tools that don’t exist in other editors. That makes it well-suited for making cryptics.
Crosserville has a few useful tools that search previously published crossword puzzles. While the editor itself is nothing special, the search tools certainly are.
PuzzleMe is interesting, because the PuzzleMe player is used by several well-known publications, like The Atlantic, The New Yorker, and the Los Angeles Times. But their editor is not very good at all. It does have some AI integration, though, which is unique.
Crossword Weaver is not very useable, but it is very nostalgic! It’s a Windows-XP-era app, and it’s still being sold to this day, for $39.95!

I compiled all my observations into a findings document. I used this document to create a list of potential feature ideas for Crosswords. (Plus, I sprinkled in some other feature ideas that I already had in mind.) This document will also be useful in the future, whenever a comprehensive overview of crossword editors on the market is needed—like when deciding what feature to implement next, or how best to implement a specific feature.

Eventually, through a discussion with my mentor, we decided that I should start by tackling a bug that I found. This will help me get more familiar with the fill algorithm code, and it will inform my decisions going forward, in terms of what features I should work on.

Introducing my GSoC 2025 project

Fri, 16 May 2025 00:00:00 +0000

I will be contributing to GNOME Crosswords, as part of the Google Summer of Code 2025 program. My project adds construction aids to the Crosswords editor. These aids provide hints, warnings, and data that help the user create better crossword puzzles.

I have three mentors:

Jonathan Blandford
Federico Mena Quintero
Tanmay Patil

GNOME Crosswords

The GNOME Crosswords project consists of two applications:

The Crosswords player, which lets you play crossword puzzles.
The Crosswords editor, which lets you create crossword puzzles.

My project focuses on the Crosswords editor.

To learn more about GNOME Crosswords, check out this GUADEC presentation that Jonathan Blandford, the creator of Crosswords, gave last year.

Crossword construction

Constructing a crossword puzzle is tricky. Constructing a good crossword puzzle is even trickier. The main difficulty lies in finding the right words to fill the grid.

Initially, it’s quite easy. The grid starts off completely empty, so the first few words that you add don’t have any restrictions on them (apart from word length). But as you fill the grid with more and more words, it becomes increasingly difficult to find words to fill the remaining rows/columns. That’s because a remaining row, for example, will have a few of its cells already filled in by the words in the intersecting columns. This restricts the list of possible words for that row.

Something you can run into is that halfway through the construction process, you realize that one or more rows/columns cannot be filled at all, because no word meets the constraints imposed on it by the prefilled cells! In that case, you would need to backtrack and delete some of the intersecting words and try again. Of course, trying to replace a word could lead to other words on the grid needing to be replaced too—so you can get a domino effect of groups of rows/columns on the grid needing to be redone!

And that’s just what you have to deal with to create a valid crossword puzzle. To create a good crossword puzzle, there are many more things to consider, some of which impose further restrictions on the words that you can use. For example:

Are the words interesting?
Are there any words that are so uncommon as to feel unfair?
Does the puzzle have a good variety of parts of speech?
Is the grid rotationally symmetric?
Are there any unchecked cells?

To learn more about the crossword construction process, check out How to Make a Crossword Puzzle by The New York Times, as well as How to Create a Crossword Puzzle by Wired.

Suffice it to say, creating a good crossword puzzle is difficult. Thankfully, crossword construction software can make this process easier—certainly not easy—but easier. For example, the GNOME Crosswords editor gives you a list of possible words for each row/column, taking into account any cells in the row/column that are already filled with a letter. We can consider this feature a “construction aid.”

The goal of my GSoC project is to add additional construction aids to the Crosswords editor. These aids will help the user create better crossword puzzles.

Construction aids

Here’s a list of potential construction aids that this project can add:

Warning for unches (unchecked cells).
Warning for non-dictionary-words.
Warning for words with low familiarity.
Indicator for average familiarity of words.
Warning for crosswordese (overused crossword words).
Heat map for hard-to-fill cells.
Parts-of-speech distribution graph.

Right now, we are in the community bonding period of the GSoC program (May 8 to June 1). During this period, I will work with my mentors to determine which construction aid or aids this project should add, what they should look like, and how they should be implemented. By the end of the month, I will have created some design docs laying all this out. That will make it much easier to hit the ground running, once the coding period starts, in June.

Mini crossword

Here’s a mini crossword that I made! You can try it out by using the Crosswords player.