Hacktoberfest is a global celebration of open source contribution that has attracted developers around the globe since Digital Ocean first launched in 2014. What started with a mere 700 developers in its first year has blossomed into hundreds of thousands of participants in recent years.

Are you a maintainer considering participating in Hacktoberfest this year? This guide is here to help you get the most out of participating.

What Makes Hacktoberfest Unique?

Before diving into the maintainer guide, let’s look at some things that make Hacktoberfest stand out as a unique opportunity for open source maintainers.

A Global Phenomenon: Hacktoberfest is the biggest online developer event of the year that draws participants worldwide. Its reach and impact continue to grow, reflecting the vibrant and expansive nature of the developer community.

Promotions and Community Events: Digital Ocean spearheads the event, but that's certainly not where it stops. Many other communities and projects run their unique events, fostering a spirit of collaboration and engagement.

A Gateway for Newcomers: Hacktoberfest is an entry point for many who are contributing to open source for the first time.

Rewards and Recognition: Awards and prizes incentivize contributing to open source and add to the event’s hype.

Diverse Participants: From seasoned professionals to novices, Hacktoberfest engages a wide range of skill levels and embraces everyone who is interested in open source contributions.

Beyond Code Contributions: While the primary focus has always been on contributing code, there's also a growing emphasis on non-code contributions. Whether documentation, design, or any other form of collaboration, Hacktoberfest recognizes and celebrates all facets of open source participation.

Preptember is the Time to Gear Up.

An ounce of preparation is worth a pound of effort. In other words, it's worth spending some time in the weeks leading up to Hacktoberfest to prepare your community to leverage the wave of newcomers without overwhelming your maintainers. Most of your success will come down to ensuring that you have top-notch contributor pathways: the processes new contributors follow when first learning how to participate in your community.

The center of this event is on GitHub and GitLab in project repos. They have both introduced valuable features to these platforms in recent years to make maintainers' lives much easier. In this article we'll show off some of these features and more. Here are the major components we’ll cover:

  • Repo templates like Contributing.md, pull request templates, and issue templates to help set expectations with contributors.
  • Readme.md is the landing page for most newcomers who first learn about your project.
  • Workflow automations for the code review process to improve code quality and efficiency.
  • Hacktoberfest-specific requirements to signal your participation in the event.

Let's take a look at each of these now.

Contributing.md

Contributors who open a PR to your repo will see the contents of this file before they click the button to create a PR. This is the best place to set clear expectations around the contribution process. Communities change frequently and Hacktoberfest is an excellent excuse for housekeeping. So, even if you already have this file in place, September is a good time to review it to make sure it’s accurate.

Here are some other tips to maximize the value of your Contributing.md file:

  • Indicate where contributors can go to find issues that are ideal for newcomers. You can define a loose category of submissions or be more explicit by using Issue labels that indicate what challenges are “good first issues.”
  • Set expectations around how long the code review process typically takes
  • Indicate where the contributor should go if they want more help with their contribution.
  • Reiterate any project-specific requirements the contributor should be aware of.
  • Highlight any contributor documentation elsewhere, such as on your project's documentation site.

There are several resources online to help generate Contributing.md files, here is one that we recommend.

PR Template

Pr templates prepopulate PR submission forms with content. The primary purpose is to help contributors share info with you, but it’s also a great place to set expectations around the contribution and the code review process. A good PR template will ask for things like the following:

  • A description of the changes.
  • Screenshots if the PR includes front-end changes
  • Links to any associated issues or an explanation for why there isn't one.
  • Verification that they are aware of any project-specific requirements.

Instructions to create a PR Template for GitHub / GitLab.

Issue Template

Issue templates provide options to contributors who want to report issues and prepopulate the GitHub issue forms with content. You can have multiple issue templates to provide better information for specific scenarios, such as reporting bugs or requesting new features. The event doesn’t incentivize GitHub issues, so you shouldn’t expect too many new issues directly from participating in Hacktoberfest. However, if you have more people contributing to your project, you’re likely to have more people encounter bugs or have ideas for improvement.

Here are some tips for drafting robust issue templates.

  • Be concise yet comprehensive. Try to minimize the amount of reading the contributor needs and maximize the information they provide in simple steps.
  • For bugs, ask the user to provide information about their platform, steps to reproduce, expected vs. actual behavior, and any steps the user took to resolve the issue.
  • For feature requests, focus on keeping the discussion focused on individual ideas. You can ask about how the change would improve their experience and for screenshots that demonstrate the desired behavior. You can also ask them to indicate whether or not they searched past issues to see if the problem has already been reported or solved.

Instructions for creating Issue templates in GitHub / GitLab.

CODEOWNERS

CODEOWNERS files automatically assign code reviewers based on modified files and directories. They are an excellent way to ensure that standard review-assignment practices are automated. For example, assigning technical writers for docs changes, front-end engineers for UI changes, or security reviews for sensitive changes. One way to more effectively manage your CODEOWNERs file is to assign teams rather than individuals because that can make managing things inside GitHub easier. 

Instructions for creating CODEOWNERS in GitHub / GitLab

If you need something more advanced than CODEOWNERs, check out our article about using gitStream to implement more intelligent code review assignments.

Readme.md

A project's GitHub Readme is often the most visited landing page on the web, so it's a critical component of making an excellent first impression with potential newcomers. However, this file is often overlooked despite its vital role in the new contributor experience. A good approach is the Standard Readme Format from Richard Littauer. In a nutshell, your Readme should have the following elements at a minimum:

  • A short, 1-2 sentence that explains what the project does and why someone should care.
  • A longer, more detailed description that outlines how the project achieves the claims in the short description.
  • Install instructions that cover the entire process, from prerequisites to complete capabilities.
  • Usage and configuration instructions that cover everyday use cases and highlight opportunities to do more.
  • Information on where to learn more and how to participate in the community.

Implement Code Review Workflow Automations

Workflow automations can be a great way to reduce the manual burden of code reviews. That’s why we created gitStream: a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. gitStream enables you to add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.

gitStream makes it easy to auto-merge safe changes, reduce the mental burden of code reviews by indicating an estimated time to review, or label PRs by the components they modify. You can also use gitStream to automatically distribute code review responsibilities and find expert reviewers based on the contents of the PR.

To learn more about using gitStream to automate the code review process, check out our article highlighting the top gitStream use cases for open source communities.

Finish Repo Setup and Start Promoting

Once you feel confident that you’re ready to tackle Hacktoberfest head-on, the last thing to do is apply the Hacktoberfest topic to your repo. It’s as simple as that! This ensures that you will appear in the official event feed. If you’re offering a prize to your community, you can also search the web for popular lists that display Hacktoberfest opportunities and ask for your project to be added.

Here are some tips to improve engagement with the Hacktoberfest community:

  • Use issue labels like “Hacktoberfest” and “Good First Issue” to indicate tasks that are good for newcomers.
  • Digital Ocean heavily promotes events during Hacktoberfest, so it’s a good idea to plan something and add it to the official event calendar.
  • Most of the action happens on the official Hacktoberfest Discord server, and they have a channel to promote your project.

Managing Code Reviews During Hacktoberfest

First, Hacktoberfest launches on October 1st, so don't be caught off guard. The first week is particularly active. Expect as much as 50% of the contributors you’ll get during the event to show up in week one.

Don't be afraid to tell people no. If they don't follow your process or project requirements or respond to your requests for changes, you can close their PRs. On a related note, take time for yourself. You don't need to dedicate the entire month to your community; your contributors can wait if you need to prioritize other things. Just make sure you are transparent when items might take longer than expected.

Also, make sure you tweak your repo templates, readme, and workflow automations to respond to the needs of your community. Sometimes circumstances or understandings change, so it’s essential to be flexible in responding to your community as the event progresses. Try to strike a balance between processes and the unique circumstances of each contributor.

There are a couple of labels you can also use to help manage Hacktoberfest submissions:

  • PRs/MRs that are labeled “spam” indicate that the author is spamming contributions for the event. This flags the contributor with Digital Ocean which may lead to the author being excluded.
  • All PRs to a repo that has the Hacktoberfest topic applied to it are eligible for the event. However, you can use ‘hacktoberfest-accepted” labels to manually indicate eligible PRs if you’re unable to give them a review before the end of the event due to time constraints.

Head over to the official Participation Guide for more details about how Hacktoberfest works.

Follow Up With New Contributors After Hacktoberfest

The last critical step of a successful Hacktoberfest comes in the months following the event because some of the event participants might stick around to continue participating in your project. You’ll want to Implement a consistent process to indicate what challenges you want to encourage your community to tackle. A steady stream of contribution opportunities increases the likelihood of people continuing to stay involved.

You should also recognize your contributors for their hard work. Send them swag, give them a shoutout on social media, or simply send them a private message to recognize their value. As part of this, you can invite contributors to participate in additional opportunities, such as speaking at online or in-person events, publishing content to your project's blog, or other things that allow the contributor to highlight themselves.

Lastly, give contributors opportunities to level up their participation. You can offer opportunities to involve active contributors in code reviews or provide them with maintainer responsibilities if they demonstrate high trust and value.

Set Yourself Up for A Successful Hacktoberfest

If you follow this guide, your community should be in an ideal position to take full advantage of Hacktoberfest's benefits. With strong preparations, responsiveness to your community, and a consistent approach to encouraging community involvement, your community will be in a place to achieve strong cohesion and growth.

If you want to join us, read this blog post about how you can join gitStream for Hacktoberfest and support clean water initiatives!

Author-Image-Ben-Lloyd.png