Overview

This blog post goes over the homepage rebuild project for the Firefox iOS app, which I led and was dev complete by release version 138. This post is mainly a self reflection of the project and I hope to share my thoughts for those who are interested.

Homepage Feature

Before I dive in, this post assumes some knowledge of how the Firefox homepage works from the user perspective. If you are unfamiliar with the homepage feature, there is a brief wiki that gives an overview of the homepage feature. You can read more details there and feel free to reach out to me if you have further questions!

Background Context

Proposal

The homepage is one of the main features in the Firefox app and we want to contiously improve and enhance the experience for our users. There was a time when our homepage code caused app crashes every other week.

One common crash that the homepage was facing was caused by the collection view layout becoming out of sync with the underlying data—often triggered by tab actions like closing tabs. This inconsistent state led to crashes when the layout expected more cells than the data could provide. There were also unsafe access patterns, like reading from arrays without bounds checks and thread-unsafe data updates in general.

To put out the fires, the team implemented temporary patches and band-aid fixes to help stabilize the application. However, these fixes were never intended to be long term solutions, as they make the code brittle and difficult to update.

Knowing that in the near future we want to experiment on the homepage, we took this opportunity to propose rebuilding the homepage instead of refactoring it. Therefore, a proposal was written to compare the two options with a recommendation to rebuild the homepage, which was eventually approved.

In the long-term, rebuilding will achieve the following benefits compared to refactoring:

• less dev time in untangling code
• less effort in pulling apart dependencies
• avoid encountering unknowns that arise when refactoring

By investing in a complete rebuild, we ensure the homepage will not only perform better, but also make it easier for future development and feature expansion.

With the approval, we began the homepage rebuild project.

Goal

The main goal of the project was to rebuild the homepage by integrating Redux for state management and using diffable data source to allow the UI to respond better to changes in the underlying data. Previously, the homepage was reloading an unnecessary large amount of times which also caused poor user experience such as flickering icons and diffable data source solves this by making updates on the differences.

There were 3 main key objectives that were listed out for this project:

A. Centralized State Management with Redux

Implement Redux architecture to centralize and standardize state management across the homepage. Each section in the homepage will have itself contained Redux components if needed. Redux will provide a single source of truth, making it easier to track, debug, and manage state transitions for each homepage section. This should significantly reduce the likelihood of state-related bugs, eliminate some usage of delegates and provide a single directional flow of information.

An example of a section using Redux architecture: The Top Sites section will have its own state (TopSitesSectionState), action (TopSitesAction) and middleware (TopSitesMiddleware).

B. Enhanced UI Updates with Diffable Data Source

Integrate diffable data source to manage dynamic content updates in the UI. This will allow the system to efficiently handle changes to the data model, such as insertions, deletions, and reordering of elements, without requiring full updates in reloading the whole collection view, which we are doing currently. This will lead to smoother and more performant UI transitions and less crashes in terms of inconsistencies between data and UI.

This implementation can be found in HomepageDiffableDataSource.

C. Improved Stability, Reliability + Maintainability

The combination of Redux and diffable data source is expected to enhance the stability and reliability of the homepage. By reducing the complexity of state and UI management, we aim to eliminate crashes and other issues that have previously affected the user experience. The improved architecture will also make the codebase more robust and easier to extend in the future. The goal is to facilitate easier onboarding to our homepage code, faster development cycles, and more straightforward debugging and feature enhancements.

From testing, there have been minimal bugs, but as of writing this blog, we are still running the experiment and confirming with metrics is still to be determined.

Expected Outcomes

More maintainable and scalable homepage architecture for future development

• Reduced instances of crashes
• Improved application stability
• Ease of development and iteration
• Enhance user experience through smoother + more responsive UI updates

Project Development

This project was in development from October 2024 until April 2024, but was not worked 100% capacity (i.e. vacation time and work weeks).

Set Up

During the initial stages of development, there were a couple of actions taken before pure code implementation.

• Estimation: To give better estimates on the project, I created a spreadsheet that outline the different tasks. Originally, the estimation provided was with two full time engineers, but due to re-prioritization it became mainly one engineer at a time.
• Epic: Created separate tasks that needed to be complete for the project.
• Public channel: Created a public communication channel so that the team and stakeholders can view any questions or status updates.
• Documentation: Internal doc that was created (I reused some of that information here).
• Architecture Diagram: Created initial diagram to confirm with the team on the architecture before implementing. Updated and used this diagram to perform handoff to engineers that will be working on the new homepage features.

Implementing New Homepage

The homepage rebuild project has been implemented and dev complete (aside from some nice to haves). Most of the new code can be found in the Homepage Rebuild folder.

Phase Breakdown

Due to the large scope of the homepage, the rebuild project was broken up into two phases. The phases were also a way to help QA test and familiarize with the homepage rebuild project without waiting until full completion. This would help catch issues earlier if needed.

Phase I - Create a foundation for the homepage using diffable data source and compositional layout and start the Redux foundation for the following subsections:

• Header
• Top Sites Section
• Pocket Section
• Customize Homepage

Also, includes wallpaper, context menu, scrolling logic.

Phase II - Continue to rebuild the other homepage subsections:

• Messaging
• Bookmarks Section
• Jump Back In

Also, includes adding telemetry + adhering to our new telemetry naming guidelines.

I foresaw that top sites and jump back in section would take the most time so I made sure to split the two in different phases to balance out the timeline. To help in keeping tracking with my progress, I would create a simple spreadsheet shown below, which really helps me when working on a self-led project.

New Telemetry Guidelines

The biggest blocker of this project was having undefined telemetry guidelines. When we received the guideline to keep the telemetry consistent with previous implementation, it was discovered that there some flaws in the existing implemention. After discussion and review, we decided to implement new telemetry that adheres to our new telemetry naming guidelines (another initiative on the team), while keeping a few the same. Going forward, having telemetry requirements upfront and defined earlier would’ve helped move the project more quickly.

Writing Unit Tests

One of the issues that the old homepage faced was flaky unit tests. Since the project was an opportunity to rewrite the homepage from the ground up, I wanted to make sure that I was developing with a TDD mindset and created solid tests. This prompted the wiki documentation - Unit tests guidelines.

The homepage project also led to developing unit tests for middlewares. This prompted creating the StoreTestUtility class and thanks to the collaboration with my team members, we also developed a better mock for testing middlewares. Our guidelines in testing with store is documented in this wiki. The issues with testing our Redux architecture is that our store and its middlewares are global and cause tests to be less isolated or testable. As we are moving forward to using a Redux architecture through the app, we are still learning what works best for our project. With that, we are still refining unit tests, such as needing to modify having the global middlewares set for the store. See more details in this PR.

Decision Table

Throughout the project, there were many decisions made and changes to the homepage as well as clarification as what we wanted. Later in the development, I decided to create a decision table in the ongoing project document, but it would have been helpful to make this table earlier. A decision table is a visual tool that allows us to systematically list decisions considered and the outcomes. It helps teams ensure consistency and communicate decisions clearly.

Testing the New Homepage

As of May 30, the new homepage is still under experimentation and hidden behind a feature flag. It can be tested in our nightly builds, or you if you pull down the Firefox iOS repo (https://github.com/mozilla-mobile/firefox-ios), the feature flag has been enabled in dev mode by default. See details on configuration in homepageRebuildFeature.yaml.

Checklist

While working on this project from end to end, I developed a checklist for myself that I hope to expand + continue for the future. Happy to hear any feedback on this list.

Initial Project Assignment

• Confirm design is finalized (+ went through design system review)
• Confirm telemetry requirements defined
• Create project documentation (notes / feature overview)
• Create public communication channel
• Create spike + develop initial architecture diagram
• Create tickets in epic

Project Implementation

• Create spreadsheet with timeline + delegate tasks
• Add unit tests / UI tests
• Accessibility review
• Post weekly status on Epic ticket or public channel
• Confirm feature works in all themes / devices (iPad, iPhone, split view, multitasking)

Project Completion

• Finalize all documentation
• Create QA Request
• Experiment created (if needed)

Final Thoughts + Wrap Up

Overall, I feel very fortunate to be able to work on this rewrite on a large feature using modern APIs and gained more confidence in working with our Redux architecture. Previously, I haven’t really worked with the homepage. With the homepage rebuild, I avoided going too much out of scope, so some areas are not adopting Redux fully and still follow MVVM (wallpapers) and the cell UI + data layer was reused. Having this experience, I was able to solidify my knowledge in diffable data source, compositional layout and improving our guidelines in Redux.

Leading this project gives me more confidence to take on bigger projects. While I was able to break a complex project into separate tasks, I would like to have worked more closely with other engineers throughout the project. I was grateful that my teammate has also helped me with wallpapers and scrolling logic when I was out of office. During the time where we were both discussing the project, I really enjoyed to conversations and pairing we had.