I'm going through my dev folder on my Mac and doing a little cleanup on files related to an Astoria Digital project that's winding down into stability. The cleanup is just to make sure that future me doesn't have to wade through a bunch of throwaway test directories related to the project in order to figure out where the real action is.
One thing I'm noticing is that I've got a number of little projects where I broke away from the main code base to experiment in isolation; these aren't branches, but rather isolated mini-projects, usually with just a file or two. This is a habit that serves me well, and I tend not to notice how often I use it until I do a cleanup like this.
I'm not sure who needs to hear this, but it's an idea worth sharing so...
Make micro repos!
Astoria Digital, a neighborhood hacker group I'm involved in, has been creating a bot to support the Astoria Mutual Aid Network since the initial outbreak of the COVID-19 pandemic in NYC. The bot helps volunteer dispatchers by getting them all of the relevant info they need to make quick decisions on which volunteers to contact for inbound help requests in our neighborhood.
A lot of the real dispatcher work happens on the phone, with dispatchers serving as the connector between volunteers and requesters. That means that how phone numbers are surfaced to the dispatchers matters.
In the beginning, the bot was not really meeting the dispatchers all of the way when it came to phone numbers. It would deliver numbers, but they were buried in a list full of other contextual information, and often the numbers were poorly formatted (whatever the user initially enter into the system came out verbatim on the other side to the dispatchers).
This meant that, depending on what the dispatcher was doing, they'd need to take one of the following intermediate steps:
- Copy and paste all of the data into a text editor and make a list of phone numbers
- Look the volunteers up by name in the database to get phone numbers
- Copy/paste poorly formatted numbers into a phone app because smartphones wouldn't recognize them as phone numbers, and thus weren't tap-to-dial
Not great, so we wanted to fix that by making sure any message going to a dispatcher included a consolidated list of well-formatted, tappable-on-smartphone phone numbers. That way, no extra legwork would be required on the part of the dispatchers to start reaching out to volunteers.
Straight to the main code base?
The trouble with implementing directly in the main code base is that I wanted to experiment quickly. Trying to iterate in the context of the bot's full universe meant that each time I tested my work, I had to do a lot of manual setup and waiting for things to happen that weren't mission-critical.
- Reset a database entry or submit a new entry
- Wait on the bot to hit our test database online
- Wait on the bot to send the output message
That could be as much as a 15-second wait just to find out I have a syntax error.
Plus, not all of the inputs my code would need to handle in production could necessarily be found in the test database.
Micro repo, hyper speed
Instead, the core of the feature I was working on could be summarized as:
- Take in a given string
- If it's a legitimate phone number, format it and return it
- If it's not a legitimate phone number, mark it as unparseable
(You may be wondering why we didn't opt to handle this with form validation or database scripts. While that would have been ideal, trust me, there are reasons why we couldn't do that in this situation.)
Based on the above summary of the feature's core functionality, that sounds like something a micro repo can handle nicely. All I really need to get started is some dummy data.
Since we're working in Node.js, the initial setup was along these lines:
npm init -y git init touch index.js data.js .gitignore echo "node_modules" >> .gitignore
Then I could simply add my test data to
data.js, and start coding in
node index.js to run the script.
By working this way, I was able to move quickly in isolation, eliminating periferal concerns and long wait times.
I pushed the micro repo I used to GitHub just to share a little of what it looked like.
Of course, I've cleaned it up considerably before pushing. For example, I didn't start out by thinking I'd use the
google-libphonenumber module, so at first I wrote another script that was doing a little DIY parsing (side bar: if you're working with phone numbers, you don't want to write the parser yourself; it's a massive challenge, and one that's been solved by other libraries, like
google-libphonenumber). I also included the JSDoc that one of the other hackers (I'm pretty sure it was Chris DeLuca) on our team kindly wrote for the main repo.
You can see the code here in the Volunteer Dispatch bot repo.
Try it out
If you're not already making micro repos for rapid iteration on tightly defined features, it's worth giving it a shot.
Doing this myself, I often notice a little inertia in the beginning, with little narratives in my head like:
- All of the inputs I need are already in the main code base and database
- Setting up another repo for this feature isn't worth the effort
- I won't lose that much time by working in the main code base
In practice, all of these narratives are frequently untrue. Often, they are rationalizations for the inertia of developing in-place.
So ask yourself:
- How can I strip this feature down to a simple input/output?
- What inputs do I need to handle?
- What outputs do I need to return?
- What test data should I create or gather?
Most of these things, you're going to end up addressing anyways. Taking a few minutes to create a micro repo can help make your answers to those questions more explicit while speeding up your iterations tremendously.