This is a submission for the 2024 Hacktoberfest Writing challenge: Maintainer Experience
Introduction
Maintaining an open-source project is incredibly fulfilling yet often exhausting. Since late July this year, I've been knee-deep in preparations for the v2 stable release for my open-source library, React ChatBotify. It is a time-consuming process, and more than once, I found myself thinking how nice it’d be if there were extra hands around to help with the efforts 😪.
Hacktoberfest, a month-long open-source event held every October seemed like it could provide exactly that. Hosted by DigitalOcean, Hacktoberfest encourages developers from around the world to contribute to open-source projects in exchange for learning, community building, and digital rewards. It was a tempting opportunity to bring in fresh contributors, yet committing to it felt daunting due to increased responsibilities. Add on to that the "maintainer's nightmare" stories I'd read about having to deal with spammy PRs arising from the event, and you might understand why I was rather apprehensive 😣.
However, as the month of October kicked off, I noticed an increase in activity on Hacktoberfest's discord server and frankly, the excitement within was hard to ignore. Although I did not plan to participate initially, I felt an urge to dive in and in the spur of a moment, I opened up my project for Hacktoberfest, eager, though anxious to see what the month would bring.
Preparation & Setup
Including a project for Hacktoberfest was surprisingly straightforward. To participate, I only needed to add the hacktoberfest topic to my repository. While the Hacktoberfest website suggested several other best practices for maintainers, having the hacktoberfest topic was technically sufficient to have my project included.
That said, I also spent some time updating the project README, developer guide, as well as contribution guidelines to ensure that they contained the most updated information. Clarity was made a high priority, so that developers can better understand what they're getting into and how to get started.
Troublesome as it may seem, I would eventually learn that this was actually the easiest part 😂. From creating issues, to managing PRs, each of them presented a unique set of problems that ranged from interesting to frustrating. Let's look back on them together in the rest of this article!
Creation of Issues
Initially, I had thought that the creation of issues would be relatively quick and simple. After all, I just had to create issues and tag them with a hacktoberfest label right? However, it proved to be more complex than expected. You see, when trying to create issues, a couple of important questions came to mind:
- Who am I catering the issues for?
- Which areas does the project need help in?
- What kind of issues to create?
- How can I help people ease into the issues?
If I wanted to create issues for my project that others would be keen to work on, I had to answer these questions.
An Initial Exploration
Since I was already in the Hacktoberfest Discord, I looked within for answers. Based on a couple days of observations, I gathered that there were a significant number of first-timers who are keen to dip into open source work. With that in mind, I decided to make most of my issues beginner-friendly. It was after all my first time participating in Hacktoberfest as well 😝.
Scoping the Issues
Due to the ongoing v2 changes, significant code rewrites had occurred across the entire project. While there was a basic integration test in place to catch the occasional obvious bugs, it is far from enough with the scale of features introduced in v2. Up till then, I had never properly put in the time and effort to setup unit testing (which would undoubtedly improve the reliability of my project).
With that in mind, scoping my issues to writing tests sounded like an excellent idea. It's a win-win-win situation for aspiring first-time open-source contributors, the React ChatBotify project, and definitely for myself 😝.
Firstly, writing tests is a valuable skill for developers to pick up. It may also comes across as less daunting for first-timers, since tests do not directly interfere with the core logic of the library. Secondly, the project itself stands to benefit from having more robust test cases. This is a particularly apt time as well given the massive rewrite that came along with v2. Lastly, I appreciate the help with writing tests, which gave me more time and confidence to work on the v2 features 😊.
Lowering the Barrier of Entry
With that said, I still had concerns about the quality of the tests that would be written, and acknowledged that beginners may benefit more from a little hand-holding or reference. It wasn't like I could just create the issues and then magically, people come along and the tests would be perfectly created (I wish 😅).
So, what better way than to provide examples within the codebase itself? The project was already neatly structured into components, hooks, services etc. For testing, it made sense to mirror this structure. Hence, before even creating the issues, I wrote several unit tests for a couple of internal hooks. These test cases were then referenced and used as examples in the issues I created for writing test cases!
Now imagine wanting to contribute to a project and being given the task details as below:
It's short and sweet, with appropriate links to the resources that you will need. Hopefully, you'll agree with me that it's pretty welcoming to beginners 😋.
A Continuous Process
Much to my surprise, the issues received a lot of attention, so much so they were being assigned out much faster than I had anticipated. Thus, throughout the month of October, I found myself continuously creating a bunch of fresh issues every few days to keep up with the growth in interest. I know what you may be thinking, but I wasn't creating issues unnecessarily 😐.
In fact, the constant creation of issues was very much possible because the project itself had a lot of components, hooks and services that could be tested individually. As part of the v2 rewrite, majority of the core library logic had been broken down into smaller, more manageable parts which facilitated easier testing.
Stale Issues
Of course, not everything goes well. Some issues became stale overtime either due to a lack of interest, or that their assignees had gone missing-in-action (MIA) 😰. This was not unexpected, though on some occasions, dropping a friendly ping to the assignees brought them back into action 😝.
All in all, by keeping issues beginner-friendly, scoped to testing and with proper references, it worked out pretty well! That said, if given a chance again, I would probably have experimented with creating a handful of challenging issues to cater for different skill levels. But hey, there's always next year!
Management of Pull Requests
Before even the first pull request came in, I knew that the management of pull requests was going to consume a significant amount of time - and it did. Out of all work involved for Hacktoberfest, reviewing pull requests took up the most time and because of that, I actually had to calibrate my approach towards managing pull requests.
A Balanced Approach
Issues only tell half the story. For every issue created, I had to be mentally prepared that there'd be one (or perhaps even more than one) pull request (PR) I have to review. However, unlike issues which were created with a structured template I curated, the solutions that came with pull requests took on various forms. This is understandable, as developers tend to have different approaches and preferences when tackling problems.
Now, there're 2 ways I could do this. One, I could be very picky, insisting that everyone write the same way and take the same approach. Or two, I could focus on the quality of the test cases themselves and close an eye to other minor differences. Some of you may be wondering why not combine both options - i.e. be picky, and focus on the quality of the test cases as well.
That's not impossible, but in the interest of time and resources, I went with an approach to strike a balance. Given that Hacktoberfest was a timed-event with many first-timers, the value of the latter felt greater. After all, it doesn't really help my case if the test cases were poorly designed. As I already had test cases for reference, I was also not expecting approaches and code styles to stray too far off. Hence, unless there was something drastically different, I didn't nitpick too hard.
Resolving Conflicts
Occasionally, multiple PRs are opened for the same issue. This happens when developers directly open a PR without first expressing interest and being assigned an issue. When faced with such a situation, I fell back to the contribution guidelines that I had clearly written:
Ultimately, it is only fair that the assigned developer who followed the guidelines gets priority in having the PR accepted. That said, I also did not want the other party to feel unappreciated. Oftentimes, I would facilitate discussions between the 2 developers to decide how best to proceed. Sometimes, the assigned developers acknowledges that he/she has not started on the issue and was willing to pass it up. Other times, the developer who opened a PR without being assigned happily took up other issues.
I was certainly lucky that all conflicts were resolved amicably, as the developers I worked with were very understanding. I greatly appreciate their help in maintaining a safe environment for the project 😊.
Stale Pull Requests
Like issues, there were also a handful of stale PRs. This happens when a PR is reviewed but there was no subsequent follow-up from the developer. For this Hacktoberfest, there were only 2 of such cases and thankfully, other developers came along to pick up the associated issues!
With that said, stale pull requests weren't much of a problem. In fact, at the end of the event, I was surprised to see the number of pull requests merged. Take a look below!
Before Hacktoberfest:
After Hacktoberfest:
A whopping 56 merged pull requests arising from the event, amazing isn't it?
Key Takeaways & Lessons Learned
Having just been through my first Hacktoberfest event, I must say it has far exceeded my expectations in terms of the value that it brings. I would never have imagined the overwhelming interests, as well as the quality of improvements that would be made to my project. Numbers don't lie - the contributors to my project has more than doubled in just a month:
Reflecting on this entire experience, I believe there a few key areas that contributed to the overall very positive experience.
Clear Contribution Guidelines
Having a clear contribution guideline is extremely important. Imagine trying to learn a game, but being given a poorly written tutorial - or worse, not even finding one. Would you still continue? Maybe, maybe not - but why take the chances?
The same applies when developers search for projects to contribute to. A clear contribution guideline lets developers have clarity on where and how to get started. For React ChatBotify, I freshened up the contribution guidelines for Hacktoberfest alongside the project README and developer guide. They most definitely have a part to play in easing developers into the project!
Quality of Issues
As you may be able to tell from what I've shared, a great amount of effort went into ensuring that issues were well curated. This meant that the issues created contained the necessary information and were of a reasonable quality.
This was important, not just for forming a solid first-impression. It actually gives developers the clarity and confidence required to tackle the issues. As a bonus, it also helps lighten the load on my end as developers are less likely to have to seek clarifications if the issues contain all the relevant information 😊.
Community Engagement
In any collaborative setting, engagement is, if not the highest, certainly one of my top priorities. For a project to thrive, the sense of community is essential — and Hacktoberfest was no exception. I made a point to respond to issues/PRs as fast as I could and provided help to the best of my ability.
This not only kept developers engaged, but also offered them the assurance that they were contributing to an actively maintained project. More importantly, they know that they are not working on issues alone.
You Define Your Own Experience
Despite best efforts, not all things will go as planned. As project maintainers, it’s easy to get caught up in tracking project metrics — like how many issues were assigned or PRs merged.
However, it's not often that we look within ourselves, and consider realistically what we think will come out of the experience. For me, I approached Hacktoberfest with minimal expectations, focusing instead on the process itself. In the end, I was pleasantly surprised, gaining far more than I anticipated and it turned out to be a very fulfilling experience 😊!
Conclusion
Looking back, Hacktoberfest went pass in a flash. It's heartening to see that even now, after the event has ended, a few dedicated developers are still working on open issues and pull requests. Prior to the event, the "horror stories" of spam PRs had me really concerned but as it turns out, the event went much better than I expected.
Hopefully, with the insights and lessons learned from this year, next year's experience will be even more rewarding! As a personal goal, I hope to introduce more challenging and a larger variety of issues next Hacktoberfest. For now, it's a wrap 😊!
Top comments (1)
Awesome read!