Contribution experience report: Organic Maps

Welcome to my sixth contribution experience report. I have done others for:

My motivation to contribute

In Saxony, many bars allow indoor smoking. As someone who struggles in smoky places, I try to avoid those bars. It’s often not so easy to look up the smoking status of a place, as it is rarely advertised online, so for a while I have been surveying bars and adding this information on OpenStreetMap, so it can be found easily. Well, easily for me, but not that easily for most people around me, because OpenStreetMap.org isn’t user-friendly. So it’s not easy to share the result of my evening walks with them.

I generally don’t use a smartphone to go to places, but that’s the norm for most people. I had the impression that the Organic Maps app is the most user-friendly way to use OpenStreetMap for the general public. Because this app does not yet display the smoking status of places, I thought I would try to add that.

First contact with the project

I first wrote an issue on GitHub to propose the feature, making a mock-up of what it could look like. The feedback was supportive and I was encouraged to make a further mock-up of what the editing experience could look like. So it felt like it was worth giving it a shot!

Development environment

I had zero experience with mobile app development (and in fact, very little with mobile app use) so this was a pretty interesting dive. The development environment is reasonably well documented and rightly warns you about the heavy resources needed to start developing. Not only is the repository itself large but so are the pieces of tooling (such as Android Studio, a tweaked version of IntelliJ IDEA for Android development), dependencies, and maps data. This heavy set up felt like a real hurdle, but I guess it’s probably forced on them by the mobile app ecosystem. The Android and iOS app are developed in the same repository, as different codebases which share some tooling and localization. They don’t have exactly the same features but seem to be quite similar. The repository also contains many other tools, primarily to generate the map files consumed by the apps, which are compiled out of OpenStreetMap extracts and other data sources. All those separate code bases have some intrinsic coupling: for instance, the binary format of the compiled maps needs to be synchronized between the apps and the generators, so that’s probably one reason to have them all in the same repository.

Finding my way into the code base

The first step to implement my feature was to include the smoking=* OSM tag in the compiled maps, by modifying the maps generator written in C++. Not knowing the code base at all I thought I would just imitate other features of points of interest, such as the cuisine=* tag indicating which sort of food is served in a place, or the wheelchair=* tag which classifies wheelchair accessibility. It involved quite a bit of trial and error, working exclusively using the test suite of the generator to validate my changes as I wasn’t sure how to inspect the binary output itself. It felt pretty much like a shot in the dark but I was counting on the code review to validate the approach. In particular, I was initially very confused by the difference between “types” and “metadata”. It seems that the former makes the information searchable, whereas the latter is just bits of information added to a node without any index, but I wish I could have read that in some documentation (if that exists?).

One oddity I noticed is the development workflow for localization: beyond the source files where translations are stored, there are other files that are derived from them and which are checked into the repository. A Python script is included to update those generated files, with the understanding that they should not be edited manually. Intuitively, those files should rather not be checked in at all and generated on the fly before building. That would get rid of a lot of commits (look for “[strings] Regenerated”).

Reviewing experience

I first went for adding smoking information as a “type”, not “metadata”, since it could be useful to search for a places based on their smoking status (like Osmand allows). The first review feedback was that I should rather add this as metadata, which turned out to be much simpler. The reviews came quickly (multiple reviews on the day the PR was opened) and felt supportive.

But then it became unclear whether this smoking status had its place in the app at all, with concerns being voiced about the usefulness of the information globally, or that its presence in the app would encourage people to smoke. I spent some time doing a survey of the usefulness of this information country-by-country in an attempt to make the case for including this information at least in some places. But even with that, it seemed that there was no clear consensus for including this status. The verdict came: you can work on it, but we might pull it out. So I gave up.

One contributor called for a holistic re-design of the UI which shows information about places, reviewing which information should be included there and under what form. I agree that it would be very useful, given that this panel is currently quite rough on the edges. It omits various types of useful information and the information it displays is often not very clear, or needlessly takes a lot of space. Adding new metadata fields in a piecemeal fashion is unlikely to improve that. But it’s unclear to me which process should be followed for such a re-design, and it feels like expanding the scope of my contribution quite a bit.

Testing infrastructure

The test suite for the C++ was good enough for my purposes as I could just imitate the surrounding context to write tests for my changes.

For the Android app, I could not find any tests, which I found quite curious. I don’t know if there are end-to-end testing frameworks for Android, but surely some parts could be covered by unit tests at least?

Code formatting

For the generator in C++, I found CPP_STYLE.md which documents the expected style with quite some detail. According to it, I can use clang-format to format my code according to the guidelines. But running clang-format -i indexer/feature_data.cpp seems to butcher everything, which isn’t great.

For Java code, I initially thought it would be handled automatically by the IDE, but sadly no, the way it is enforced is by relying on reviewers to manually add comments in the PR about the code style, which doesn’t feel like a great use of everyone’s time.

Governance and roadmap

I could not find any document about the governance of the project. I have been told it is in docs/GOUVERNANCE.md.

I did not find a page about a roadmap either, but the general direction of the project seems relatively clear to me: the state objective seems to be a viable FOSS competitor to Google Maps, with a focus on privacy and cleanliness from undesirable app features.

Would I contribute again?

Probably not, given the various problems I encountered.