Fixing Sorting and Visibility Issues: A Development Diary in Open Source Projects

Hello!! 👋

Freifahren and Impress are two exciting projects I’ve been working on. Recently, I had the opportunity to address two critical issues: sorting station names in the ReportForm for Freifahren and reordering visibility options in the dropdown menu for Impress. Below is a breakdown of the challenges, solutions, and lessons learned along the way.

---

Freifahren: Fix Sorting Order of Stations in ReportForm

The Problem

In the ReportForm, station names were being sorted alphabetically by their IDs, rather than by their names. This caused confusion, as station names are a more intuitive way for users to locate entries. Issue 300

Challenges Encountered

During the process, I faced a few challenges:

1. Missing Environment Variables: The RISK_API_URL was required during backend setup, but its purpose wasn’t clearly documented.

   After consulting with the maintainer, I learned that the variable is related to a microservice for calculating risk. Since it wasn’t necessary for this task, I could safely ignore it.

2. Content Moderation Microservice: Submitting a report involved hate speech detection using the CONTENT_MODERATION_SERVICE_URL. Without it, the PostInspector route returned an Internal Server Error.

   The maintainer clarified that I could access the service at http://88.99.56.234:9090 or run it locally using the provided documentation.

3. Misunderstanding the Issue: Initially, I thought the sorting issue was in the ReportsModal, but the maintainer clarified it was actually in the ReportForm.

The Solution

Once I was set up, I implemented the following changes:

1. Pre-Sorted Stations: The possibleStations list in the ReportForm is now pre-sorted by name using sortedAllStations.
2. Dynamic Sorting:
   • Stations under a selected currentLine are now sorted dynamically from allLines.
   • Searches and selections from currentEntity use the pre-sorted sortedAllStations list.

These changes ensure that stations are displayed in a user-friendly order, improving the report submission experience.

The fix was submitted in Pull Request #320.

---

Impress: Reorder Visibility Options in Dropdown Menu

The Problem

In Impress, the visibility options in a dropdown menu were not ordered logically, which made the selection process unintuitive. Users expected a progression from the most restrictive to the least restrictive option. Issue 397

Proposed Solution

The expected order was:

1. Restricted
2. Authenticated
3. Public

This change was implemented in the LinkReach component, located at src/frontend/apps/impress/src/features/docs/doc-management/types.tsx.

Implementation

By reordering the options in the type definition, the dropdown menu’s display order was updated across the application. This simple change greatly improved the usability of the menu.

The updated logic was submitted in Pull Request #441.

---

Lessons Learned

1. Clear Documentation is Crucial:

   Having clear, comprehensive, and well-organized documentation can significantly streamline the development process. It helps new contributors quickly get up to speed and reduces the potential for misunderstandings or delays.

2. Communication is Key:

   Regular discussions with project maintainers ensured that I was aligned with the team’s goals and expectations, making the development process smoother.

3. Small Changes Have a Big Impact:
   Fixes like sorting station names and reordering dropdown options may seem minor, but they have a significant effect on user experience and interface intuitiveness.

---

Conclusion

These updates in both Freifahren and Impress demonstrate how small changes can have a big impact on usability. The process highlighted the importance of clear documentation and effective communication within open-source communities. By addressing these issues, we've made the systems more intuitive and easier to use, paving the way for smoother interactions in the future.