3 Ways to Get Unstuck while Fixing Bugs

#opensource #hacktoberfest

When you contribute to open source projects, getting frustrated with arbitrary issues is inevitable. I was in the same situation while trying to resolve an issue about writing a demo cloud function for one of Appwrite's features. There were 3 resources that helped me get through the problems:

Documentation
Community Channels
GitHub Issues

Context

Let's take a look at the issue for an overall context:

Your task is to implement generateOpenStreetMap function. You can look at the existing Appwrite Functions demo in the coding language you prefer to see how it works.

This function should take latitude and longitude as an input, generate map preview using OpenStreetMap API and save it into Appwrite Storage.

There were 3 main challenges I had to tackle:

Creating an Appwrite Cloud Function (I can somewhat understand the process)
Write my code in Ruby (doesn't look really bad)
Implementing OpenStreetMap API (absolutely clueless)

📜 Documentation

While experimenting with a new technology, you should seek out its documentation first. You can find the answers to most of your questions there. If you try asking for help before reading the docs, you'll probably get this kind of response:

Well, not really that rude, but they will tell you to read it first most of the time. In my case, thanks to their docs, I could easily create an Appwrite Function for Ruby. The process was pretty straightforward, so instead of discussing it with someone else, I just tested it myself.

On the other hand, documentation can sometimes be outdated or too hard to navigate to the part that you need. In fact, OpenStreetMap Wiki took me quite a lot time to find out how I could retrieve a map image from their API. Because even the search box can't find any explicit example of such functionality, I struggled for a few days until I decided to reach out to the next source of support: community channels.

💬 Community Channels

Almost every open source projects that welcome contributors use a platform for communication (e.g. Discord, Slack, and Matrix). This should help you resolve most issues which can't be found in the docs.

Just kidding. Most of the time, you'll get more helpful advice. For example, I realized my initial approach to get a map image from OpenStreetMap API was a dead end after discussing it with a project member on Appwrite's Discord server. Thankfully, I was introduced to OpenStreetMap tile server, where I can get a static map image from a tile number. Moreover, I even found the exact code snippet from the docs for calculating the tile number from a latitude, a longitude, and a zoom level:

# Source: https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Ruby
def get_tile_number(lat_deg, lng_deg, zoom)
  lat_rad = lat_deg/180 * Math::PI
  n = 2.0 ** zoom
  x = ((lng_deg + 180.0) / 360.0 * n).to_i
  y = ((1.0 - Math::log(Math::tan(lat_rad) + (1 / Math::cos(lat_rad))) / Math::PI) / 2.0 * n).to_i

  {:x => x, :y =>y}
end

🎫 GitHub Issues

Sometimes, when something doesn't work as expected, it's not your fault. It can be a bug that has yet to be detected. Even if it is not, you will get more attention to your issue when you file it on GitHub.

While testing my cloud function on Appwrite Console, I got a bizzare error with my HTTP requests. After doing a lot of research online and asking for help on Discord, I still had no clue. When I was about to give up, I decided to file an issue on Appwrite's repo saying how my function didn't work as expected. After a while, I got a response.

After following his suggestion, I managed to fix the bug and eventually made a pull request. You can check out my recent blog post to learn more details about how I implemented and deployed the cloud function.

This is my last blog post for Hacktoberfest 2021. It was truly an amazing and eye-opening journey! I'm really looking forward to participating in Hacktoberfest again next year.