GSoC Week 6

Documentation is one of the pillars of good software. We often forget to do it because it comes in as a 'secondary' consideration. My theme for week 6 was 'documenting my features properly', and it was what I did.

Weekly Check-in

We had a lengthy check-in session, especially because my lead mentor Storm was starting a small holiday this week. The topics, however, revolved around putting the finishing touches on pending tasks so that we could progress to the stretch goal (AI). We agreed on a follow-up meeting to discuss the AI requirements on another day.

Among some of the finishing touches discussed were:

1. Drafting the upgrade considerations that would added to the release notes for whichever new version of Wagtail the feature would fall under.
2. Updating Wagtail's documentation. In the examples, I would have to replace instances of ImageChooserBlock with ImageBlock, and I would also have to update the StreamField reference guide to show the new block.
3. Following up with my feedback request on the image description field warning labels.
4. Making the social media RFC post.
5. Iterating to make ImageBlock perfectly swappable where ImageChooserBlock has already been used, without any data migrations.
6. Going through fresh comments on the RFC.

We structured the next sprint from the outcomes of our meeting discussions.

AI Follow-up Meeting

On Wednesday, we discussed the rough (proof of concept) implementation and how to get started. We agreed that our first AI model would be the same as what we used for our research on alt text: OpenAI. We discussed what the contract should look like between our service and the APIs we would use.

My mentors were of the idea that I would start the implementation as a simple Python project, and after getting things to work, we would progress to modifying it to be an extension of Wagtail. The primary focus, however, was on getting the feature set to work. They both gave me some pointers on things to look out for and things to try. We also realized some more questions that would pop up much later in the Wagtail implementation, such as whether to generate many different results with the same prompts at once vs just one result (with the option to trigger for more). There was also the question of whether we would make a UI option to allow editors to modify the existing prompts, or whether to let it be site-wide.

There was also the question of an RFC for the new feature, but we agreed that since we weren't sure of the direction or the complete implementation, we would build iteratively until we had enough knowledge of what to include/exclude from the RFC, as well as questions that may come up later on.

Challenges

I had a couple of challenges, but I scaled through them like a superhero. The first challenge was that I wanted ImageBlock to be a perfect replacement for ImageChooserBlock. In Wagtail, when you want to change the block used, you will very often have to do a data migration. It can be an annoying step, and in some cases might prevent people from upgrading right away, or from changing to the new way of doing things (especially since ImageChooserBlock wouldn't be deprecated). The all-encompassing goal of my GSoC project is to get Wagtail editors to follow best image accessibility practices, and the easier I can make it, the better the chances. I had the ambitious goal of erasing the data migration step.

To do this, I had to modify the new ImageBlock's to_python and bulk_to_python to be able to receive data in the same format that ImageChooserBlock would have received it. The solution involved me adding some conditionals to the methods, and they would check if the received value was an instance of int (image_id). If it were, I would retrieve the image object, and then I would create a dict with the image property, and two other fields for decorative and alt_text and default them to False and an empty string respectively, before calling the next method. Writing the tests for this was another big of warfare, but I got things working.

My last notable challenge was trying to draft upgrade considerations and update the documentation. I had never written upgrade considerations and therefore had to go through some from previous release notes. I did this as a Google Doc draft and got Storm to review it. Afterward, I reached out to Wagtail's lead dev (I'll get permission to post his name here soon) for guidance on what part of the Pull Request to introduce it into, and he gave me feedback. I also asked him if it was okay for me to replace ImageChooserBlock with ImageBlock in the documentation examples it appeared in, as well as any extra pointers to look for. He was perfectly fine with it, and I spent the rest of my week working on docs.

What I learned

I once again found myself in a situation where I wasn't entirely sure of the expected data to be received from a block, but I used the SQLite Browser to inspect what it would look like. Another block was added to my list of competencies. 😅

I learned the process of prepping documentation for features, as well as some little bits of the sphinx tool for documentation in Python projects. I'll also add that modifying the to_python and bulk_to_python methods was a huge learning experience for me, especially concerning how it handled expected data.

I'm getting to the point where I have an idea of where anything I'm looking for in the codebase would probably be found.

This was another great week, and a big thanks to you for reading thus far.

Cheers. 🥂