As engineers, we all know the feeling of encountering a stubborn bug that defies easy resolution. The Gitpod team recently faced such a challenge when we discovered a bug with our Gitpod Docs Search functionality during a comprehensive documentation restructure. The search feature was not updating correctly, returning outdated data even after we manually ran an Algolia indexing query to update the production data with newly deployed changes. This left us scratching our heads, wondering how to resolve the issue and ensure that our users could access the most up-to-date information quickly and easily.
As an engineer on the team, I was determined to discover the root of the problem and resolve it as quickly as possible. This is the story of how I reverse-engineered the problem, identified the cause, and ultimately solved the Gitpod Docs Search issue.
The first step in tackling this bug was to examine the existing code implementation for the search and Algolia integration on our website. Through this process, I discovered that we were using the docsearch package, which is a JavaScript package for Algolia DocSearch. In fact, our search implementation relied heavily on docsearch, and it was clear that any issues with the package could potentially impact the entire search functionality.
Further investigation revealed that Algolia had changed its API architecture on 17th January 2022. (We patched the bug on Sep 30 2022) , marking "appId" as a required field. However, the docsearch package that Gitpod was using introduced a "dummy" app ID to compensate for this change. This mismatch was preventing the search functionality from updating the data correctly, which would be frustrating for Gitpod's users.
You can find this here
To resolve this issue, I raised a PR to fix the bug. This involved changing the docsearch package's implementation to use the actual Algolia app ID, rather than a "dummy" one. With this change, the search functionality was able to update the data correctly, ensuring that our users had access to the most up-to-date information.
[Major] fix: Algolia Search Integration
#2829
Related Internal Discussion
Algolia Changed their APIs architecture and marked appId as a required field. To Tackle that docSearch by default added appId===undefined?"BH4D9OD16A". So Integration was not failing, But the Major Issue was that it was not even indexing the New Data Since January 2022.
This PR Introduces the appId to Algolia Integration & New Docs is getting Indexed now.
However, this was not the end of the story. It soon became apparent that the fix had inadvertently introduced another bug. Specifically, the search was now returning results for documents that were not intended to be included in the search. This was clearly not acceptable, and I set to work on identifying and resolving this new issue.
Through further investigation, I discovered that the new bug was caused by an unintended consequence of the original fix. Specifically, the fix had made the search functionality too broad, returning results for documents that should not have been included in the search. To solve this problem, I needed to find a way to restrict the search to only the documents that were intended to be included.
After much experimentation and testing, I developed a solution that involved introducing a new configuration variable to control the search scope. With this change, the search functionality was able to restrict results to only the intended documents, while still updating data correctly and providing users with the most up-to-date information.
In the end, this bug served as a valuable reminder of the importance of thorough testing and debugging in the development process. It also demonstrated the technical skills and persistence required to tackle complex coding problems in a fast-paced, constantly evolving industry.
As engineers, we must always be ready to face the unexpected and rise to the challenge of solving difficult problems. By staying focused, diligent, and determined, we can overcome even the most stubborn of bugs and ensure that our users have access to the best possible user experience. The Gitpod Docs Search issue serves as a testament to the importance of these values, and I am proud to have played a part in solving it.
Top comments (0)