Jump to content

User:Hussein m mmbaga/GSoC 2026/Final-Report

From mediawiki.org
GOOGLE SUMMER OF CODE 2026 FINAL REPORT
Project: Enhancing Wikisource Bulk OCR User Controls and Feedback Modal

Information

[edit]

PROJECT DESCRIPTION

[edit]

Wikisource is an online wiki based digital library operated by the Wikimedia Foundation where volunteers transcribe old books and documents. Every page starts as an image and volunteers use OCR tool (Optical Character Recognition) to turn that image into text. The Bulk OCR feature allows volunteers to OCR multiple pages of a book at once instead of doing it page by page manually. The main goal was to build a feedback model for volunteers to OCR multiple pages and review step before the text is saved to the wiki. User should see the OCR pages results and approve them.

I have been an active Wikimedia volunteer since I started university in 2021. I review edits, help new contributors and volunteer to improve Swahili content. I see everyday how much good tools matter. Many old books and documents exist only as scanned images that nobody has typed up yet. To have Bulk OCR tool means these documents can be turned into text faster and shared.

FIRST MICROTASK

[edit]

What problem was I solving?

[edit]

Bulk OCR showed a "success" message even when some pages had failed. This is misleading and unsafe a user could think everything worked when it did not.

What did I build/change?

[edit]

I changed the notification logic so the failed page information is passed to the handler and the correct message is shown based on how many pages failed. I also made the notifications consistent for both success and failure show a clear message and the user can close it with a proper button in the corner.

What was the final result?

[edit]

This was my first task and it taught me the whole Wikimedia workflow reproduce, fix, test, push and respond to review. Bulk OCR moved all of its success and failure feedback into the new dialog window (T433033, T433174, T433182). The patch was abandoned in favour of the dialog approach. The change is kept on Gerrit for the record.

Abandoned

The Main Work: What I Built

[edit]

The heart of the project was building the feedback dialog review step. First with my mentors I built a clickable prototype so everyone could see and understand on how bulk ocr tool work. Working through options like this and adjusting the prototype until everyone agreed taught me that design is a conversation and that a shared visible prototype makes that conversation far easier than words alone.

Once the design was approved and ensure i understand the task I split the work into small connected patches instead of one huge change. This kept each piece focused and easy to review. To organise it I created sub-tasks under the parent task T394131 each for one unit of work.

Task 1 : The feedback dialog

[edit]

What problem was I solving?

[edit]

Bulk OCR wrote text straight to the wiki with no chance for the user to look at it first. There was no review step at all so bad OCR could land on pages before anyone noticed.

What did I build?

[edit]

This is foundation of the whole feature a dialog that appears after click OCR button and shows the OCR results so the user can review them before anything is saved. It shows the OCR text next to the page image in a split-view layout with Approve and Cancel buttons.

What was the final result?

[edit]

Image and OCR text showing side by side inside the feedback dialog with Approve and Cancel buttons.

Merged

Task 2: Wrap the split view in Booklet Layout showing sidebar and list pages

[edit]

What problem was I solving?

[edit]

A book has many pages and the first dialog showed them in a way that was hard to move between. The user needed a clear way to jump from one page to another.

What did I build?

[edit]

I wrapped the dialog contents in an OOUI BookletLayout which gives an outlined sidebar where each page is its own entry. Clicking a page in the sidebar shows that page OCR text and image.

Why did I choose this approach?

[edit]

BookletLayout is the Object-Oriented User Interface (OOUI) component made exactly for a set of pages with a navigation outline so it was the right tool instead of building my own navigation from scratch.

What was the final result?

[edit]

A clean sidebar where the user can move between all the pages of the book.

Merged

Task 3: Add safety banner at the top of the feedback dialog

[edit]

What problem was I solving?

[edit]

Notify the user the approve button affects many pages of a book at once which is a big action. The user needed a clear warning so they understand the effect before they click approve button.

What did I build?

[edit]

A safety banner at the top of the dialog that warning the user when click Approve it affects multiple pages. As part of this I also moved the per page layout code into its own file so the code was clean and easier to maintain.

What was the final result?

[edit]

A clear safety warning banner and clean code structure.

Merged

Task 4: Open at the start and indeterminate progress bar showing background OCR processing

[edit]

What problem was I solving?

[edit]

A big book might have hundreds of pages. Running OCR on all of them before showing anything means the user waits for a long time with no feedback.

What did I build?

[edit]

The dialog now opens right away before OCR finishes showing a progress bar and a live "OCR progress: X/Y pages processed" label. Each page streams into the sidebar as its own OCR completes. When processing finishes the progress row disappears and if no text came back at all an error state is shown inside the dialog.

Why did I choose this approach?

[edit]

Showing progress and streaming results gives the user immediate feedback and lets them start reviewing early pages while later ones are still processing. This came directly from a discussion with my mentor and wikisource community reviewer about large books.

What was the final result?

[edit]

The dialog opens instantly shows live progress and fills the sidebar in correct book order as OCR runs.

Merged

Task 5: Set the Approve action to write OCR text to page text layer

[edit]

What problem was I solving?

[edit]

The whole point of Bulk OCR is to get the reviewed OCR text into the pages. The Approve action needed to actually save the text to each page and it needed to handle failures properly instead of pretending everything worked.

What did I build?

[edit]

When the user clicks Approve the OCR text of each page is saved to its Page namespace through the MediaWiki edit API. The dialog stays open during the save and shows a "Saving X/Y pages saved" message. On full success the dialog closes and success message appears and saved pages in the Index pagelist and On failure an error appears inside the dialog. You can retry or cancel and a retry only re-tries the pages that have not saved yet.

Why did I choose this approach?

[edit]

Keeping the dialog open during the save means errors can be shown in context right where the user is looking instead of in a separate notification they might miss. Retrying only failed pages avoids a real bug because pages are created with a "create only" flag retrying already-saved pages would incorrectly report them as failures.

What was the final result?

[edit]

Approve reliably saves the OCR text shows clear progress and errors updates the pagelist correctly and retries only what actually failed and also updating the pagelist after a save.

In review

Task 6: Make the OCR text editable

[edit]

What problem was I solving?

[edit]

The early prototype idea was that a user might want to fix small OCR mistakes right inside the review dialog before saving instead of saving wrong text and correcting it later.

What did I build?

[edit]

I replaced the read-only OCR text with an editable text box for each page so the user could correct the text before clicking Approve and I made the save flow use the edited text.

Why did I choose this approach?

[edit]

It came straight from the approved prototype and it seemed to support the project goal of reducing faulty OCR text by letting the user fix errors early.

What was the final result?

[edit]

Abandoned on purpose. During review Sam questioned whether editing belongs in Bulk OCR at all since Edit-in-Sequence is the dedicated tool for editing many pages. I took the question to my mentors and We had a discussion and decided Bulk OCR should focus only on getting text into pages. So I abandoned this change and rebuilt the save flow without editing the dialog now shows the text read-only for review. The change is kept on Gerrit for the record.

ABANDONED

Task 7: Warn about unsaved changes on cancel

[edit]

What problem was I solving?

[edit]

If editing existed a user could type corrections and then click Cancel by mistake and lose their work. This change was meant to warn them before discarding unsaved edits.

What did I build?

[edit]

A warning that appeared when the user tried to cancel with unsaved edits with the choice to continue editing or discard. It only detected a real change typing and then deleting back to the original counted as no change.

Why did I choose this approach?

[edit]

It protected the user edits and a discard warning is a common expected pattern for any form with unsaved changes.

What was the final result?

[edit]

Abandoned on purpose. This change only make sense if editing existed. Once the mentors decided on the OCR-only scope and editing was dropped this warning was no longer needed so I abandoned it too. The change is kept on Gerrit for the record.

ABANDONED

Current Project Status

[edit]

The core Bulk OCR review and save workflow is complete and works as one clear feature. A user opens an Index page and clicks Bulk OCR. A dialog opens right away with a safety banner and a progress bar. Pages stream into the sidebar in book order as OCR finishes. The user reviews the OCR text beside each page image and clicks Approve. The dialog stays open during the save shows a saving message and then either closes on full success or shows an error inside the dialog with retry on failure keeping saved pages marked accordingly and failed pages unmarked.

Demo of the Bulk OCR feature for Wikisource, built during Google Summer of Code 2026.

The project currently has four merged changes and two changes under review with feedback addressed. Two changes were intentionally abandoned after the decision to keep Bulk OCR focused on OCR rather than text editing. I also tested existing functionality that did not require new code, including access restrictions, OCR engine, rotate option and language selection.

How to Enable Bulk OCR for a Community

[edit]

Bulk OCR can be turned on for a Wikisource language community by adding that community language code to the configuration.

To enable it the language code is added to the Bulk OCR list in the configuration file in the mediawiki-config repository. Once the language code is added and the change is deployed Bulk OCR becomes available on that wiki.

Important: For now Bulk OCR is only visible to administrators. Regular users will not see it yet. This is on purpose so that communities can test it carefully before it is opened to everyone.

For reference, here are the configuration patches that show how this is done:

A community that wants Bulk OCR enabled can ask a developer to add their language code to this configuration using the patches above as examples.

What Is Left To Do

[edit]
  • Follow up on the remaining in-review patches. If there is anything to improve or add on T433182 during review, I will be happy to do it.
  • Reuse the dialog window instead of creating a new one each time Bulk OCR is clicked. Sam (reviewer) raised this as a good follow-up during review of task https://phabricator.wikimedia.org/T433174

Learnings and Skills Gained

[edit]
  • I gained practical experience working on a large open-source codebase and collaborating through Git, Gerrit and code review. I improved my ability to understand and extend code, write maintainable code and respond effectively to feedback from mentors, community and reviewers.
  • Working with a chain of connected patches strengthened my Git skills particularly rebasing, resolving merge conflicts and maintaining a clean patch history. I learned to safely incorporate changes from other contributors and to verify exactly what would be submitted before pushing.
  • I also developed a stronger understanding of testing and responsible development. I learned to test real success and failure cases rather than relying on shortcuts and to consider the impact of my changes on users, translators and future maintainers.
  • I improved both my technical and collaborative skills and gave me a better understanding of how software is developed and maintained in a large open-source community. I will continue contributing to open source and to apply these practices in my future work and teach others.
  • I learn that regular communication with mentors and the Wikimedia community through Zulip, Phabricator, Email and regular progress reports. It helped to receive feedback early, discuss technical decisions and keep the project aligned with its goals. Writing regular reports also helped me reflect on my progress and identify challenges that needed attention.
  • What I learned from code review

Merge coordination. Sam (reviewer) wrote a small patch to improve my safety banner styling and it touched the same method I was rewriting. Instead of merging both blindly and making a mess we agreed an order on Gerrit he would merge first and I would rebase on top. His patch merged and i rebased to kept my page streaming code adopted his cleaner banner code and everything came together. I never do that now i know Two people can improving the same file at once is normal not a failure the skill is to communicating about it. 1325231

lesson: code review is mentorship not an obstacle. I made a habit of replying to every comment marking threads resolved once fixed, asking for clarification instead of guessing and never taking feedback personally. I will remember this for the rest of my career.

  • What I learned from working with others and making decisions

I built two patches to let the user edit the OCR text right inside the dialog with a warning if they tried to cancel with unsaved edits. Then reviewer Sam asked a simple question on the editable-text task he said editing do not belonged in Bulk OCR at all because Edit-in-Sequence is the tool made for editing many pages and Bulk OCR should just get the text into the pages. I took it to my mentors and we had discusion with both and decide to keep Bulk OCR focused on getting text into pages and leave editing to Edit-in-Sequence. This made the feature clearer and easier to use and maintain and it was the right call.

The lesson: scope is not fixed and a good reviewer questioning your feature is a gift not an attack. When a scope question comes up do not defend and do not silently obey bring it to your community forum, channel specific for developer discussion about the feature or mentors to decide together and then act.

The abandoned changes are still visible for the record:

Challenges and Solutions

[edit]
  • Docker DNS configuration the OCR service could not reach localhost. Because the OCR service could not reach my local wiki and i neede a Commons hosted file to test the success path. This was hard to see or understand at first and it cost me real time. I overcame it when my mentor directed me to read the InstantCommons manual (https://www.mediawiki.org/wiki/Manual:$wgUseInstantCommons). After enabling InstantCommons my local wiki could fetch a real book hosted on Wikimedia Commons which gave me a reliable way to test the full success path from then on.
  • The Docker image broke my local Xdebug configuration. After container restarts Xdebug settings were lost and PHP became very slow which made the environment hard to work in. I overcame this by writing a small step to disable Xdebug in the container after every restart and I made it part of my routine so it never slowed me down again.
  • Learning a large unfamiliar codebase and framework MediaWiki and OOUI are huge to Understanding how ProcessDialog, BookletLayout, MessageWidget, ProgressBarWidget and the PendingElement .etc together along with the API and the translation system to doing it well enough to extend them properly took serious study and a lot of reading before writing. I overcame this by reading the existing code carefully before adding to it, Following the framework own patterns instead of inventing my own and learning on code review and discussions with my mentors to understand the project conventions and make better implementation decisions.

Acknowledgement

[edit]

Thank you to my mentors Parthiv Menon (@theprotonade) and Satdeep Gill (@SGill) for their steady guidance their weekly and day to day support with clear direction at the key scope decision and their patience. Thank you to Sam Wilson for detailed constructive code review that made both the feature and me better and for the good collaboration on merge order and design. Thank you also to Sohom and to the wider Wikisource and Wikimedia technical community and Google Summer of Code administrators whose messages kept me informed.I will continue contributing to open source and to apply these practices in my future work and teach others.

Retrieved from "https://www.mediawiki.org/w/index.php?title=User:Hussein_m_mmbaga/GSoC_2026/Final-Report&oldid=8572400"