Preptember - How to setup your project for Hacktoberfest

Every year in October open-source enthusiasts from all over the world gather together virtually to celebrate the community, by contributing to software that is freely available to use, redistribute, and modify. Many of us rely on open-source projects in our everyday lives, which are maintained by passionate people, but what do they get in return?

By Joining Hacktoberfest, contributors can learn new technologies, showcase their knowledge, build their professional network, and give back to the community.
Hacktoberfest is DigitalOcean’s annual event that encourages people to contribute to open source throughout October. The core values are:

• Everyone is welcome
• Quantity is fun, quality is key
• Short-term action, long-term impact

DEM’s story

Development Environments created for implementing embedded software often include multiple different software tools. A great way to keep the toolset under control for the whole project lifecycle is to apply containerization techniques. Although containerization has many benefits, working on multiple projects can easily lead to several different container images.
At axem, we also reached a point where it became quite difficult to keep track of the tool images required for the projects. Hence we created a script that could be used to assign the images to the projects.
As we saw that containerization started to become quite popular in the embedded field, we decided to open up the script for the community. Our intention was to give back to those who helped us and countless others along the way. This was the beginning of the DEM.

We believe in the positive impact of having an outsider’s opinion, but our project is quite young and in this phase, it is hard to encourage people to collaborate. So we decided that we would like to nominate DEM as a project open for contribution in Hacktoberfest 2023.
Since opening the source, several new releases have been created from the DEM project, but all the implementations were done by the axem team, based on our inner processes. To be able to guide our new contributors properly, we had to make the DEM contributor-friendly.

Preparing the DEM GitHub repository

Nominating a project for Hacktoberfest doesn’t have any requirements, except maybe using the “hacktoberfest” topic and label in the repo. However, t*here are some best practices to make your issues more appealing* to potential contributors. Here are our two cents:

• Create a Contribution Guideline that is easy to follow
• Create a welcoming Code of Conduct
• Choose some issues that look interesting, have a well-defined scope and clear description, and apply the “hacktoberfest” label to them
• Create issue and PR templates for maintainability
• In the README, highlight that the project is participating in the Hacktoberfest

If you just started your own project, the Open Source Guide is an excellent content on how to launch and grow an open-source project.

In the next chapters, I provide more details for each point mentioned above. As the DEM is hosted on GitHub, the descriptions will be specific to the GitHub platform.

Creating a Contribution Guideline

A Contribution Guideline has several essential purposes like maintaining consistency, clarifying expectations, and ensuring quality control.
First, we need to consider the specific goals of our project and decide on the types of contributions we are looking for.

In DEM we expect two kinds of contributions:

• Creating a new issue: Here a contributor can file any feedback, bug report, or feature idea.
• Submitting a PR: The implementation of a specific issue. Both code and no-code modifications.

After we defined the specific goals we had to decide on the format of the guideline. The most common format is a Markdown (.md) file named ‘CONTRIBUTING.md’.
Before creating this file we should be aware of the concept of special treatment for certain files within a GitHub repository. Some files are treated differently in a GitHub repository if they match a naming convention and are stored in either the root, the docs, or the .github directory. An example is the 'CONTRIBUTING.md' file. This way GitHub will recognize the file as a contribution guideline. To create the file you can follow GitHub’s step-by-step guide.

When filling in the details, for better understanding we broke down the guidelines into two main sections. After a short introduction, we described how to create and work on an issue in the DEM project. In the second part, we explained how one can start to work with the source files and test their modifications.

Creating a Code of Conduct

By accepting outside contributors, the community grows with the new members. To establish a set of clear guidelines and expectations for behavior and interactions among community members we created a Code of Conduct. Our goal is to make sure that every newcomer feels welcomed and appreciated. Maintaining a safe space can be a daunting task for project maintainers. Everyone has their own value system, so establishing the ground rules can reduce the occurrence and intensity of conflicts.
Writing a Code of Conduct from scratch is a challenging task. Fortunately, GitHub provides a well-written template that project maintainers can customize for their use case.
The Code of Conduct can be stored as another special file of GitHub, called the 'CODE_OF_CONDUCT.md'. Again, this file needs to be placed in either the root, the docs, or the .github directory, so GitHub will automatically recognize it and load it to the Code of Conduct label of the About section.

You can find a step-by-step guide to create a CoC here.

Preparing issues for open-source contribution

In Hacktoberfest, new contributors often embark on projects with which they may have little familiarity. Expecting them to understand the whole architecture, especially in the case of complex projects, is unrealistic. So it is the maintainers’ task to offer guidance and support in navigating these challenges. To make the journey smoother for both contributors and project maintainers, consider these tips and tricks when selecting issues that are most appealing to potential contributors:

• Issue independence: Issues should not be interdependent or block other high-priority tasks. Project management can quickly become complex if contributors must wait for other tasks to be completed. On the flip side, issues that are reliant on unresolved dependencies may deter potential contributors.
• Well-defined scope: Contributors are more likely to engage with an issue if its scope is well-defined and easily graspable. Issues with ambiguous or broad objectives can be intimidating for newcomers.
• Detailed issue description: To facilitate understanding and engagement, it's crucial to craft detailed issue descriptions. A graphical representation like a flowchart or diagram can always help.
• Utilize issue templates: Issue templates can significantly enhance the contributor experience. Templates provide a structured framework for issue reporting, ensuring that essential details are not overlooked. They make the overview of issues cleaner and more organized, helping contributors focus on the task at hand.
• Link relevant documentation: Whenever possible, link relevant documentation to the issue. This includes references to project documentation, coding guidelines, and any relevant resources that can aid contributors in understanding the project's context and requirements. Accessible documentation encourages informed contributions.

If the list of issues is ready, the only thing left to do is to assign the “hacktoberfest” label to them. You can also use the “good first issue” label to help new contributors to find issues, which are easy to start with.

Creating templates

GitHub PR template

To maintain consistency and traceability in our DEM repository, we have added a PR template. This template includes the following key sections:

• Checklist: There are certain requirements that must be fulfilled before a modification can be applied. Contributors can use a checklist to ensure that these requirements are fulfilled, marking them as completed. GitHub tracks the checklist's status, providing a clear indicator of progress.
• Related issue: Here, we encourage contributors to reference the issue that the PR addresses. This link enhances our project's traceability significantly. Both our project management tools, Jira and GitHub issues, display linked PRs in the issues' properties, streamlining our workflow.
• Type of change: To categorize PRs effectively, we've included properties related to the type of change being introduced. Contributors can specify whether the PR constitutes a bug fix, a new feature, a breaking change, or a documentation update.
• Description: In this section, contributors provide an in-depth and detailed description of the proposed modifications. This description ensures that reviewers and other contributors have a comprehensive understanding of the changes being made
• Test cases: We request that contributors outline how they have tested their modifications. This transparency in testing methods helps maintain the project's reliability and quality assurance.
• Screenshots: Sometimes, visual aids in the form of screenshots can help the understanding of the behavior changes introduced by the PR. We encourage contributors to include such screenshots when applicable.

You can follow this step-by-step guide on how to create a PR template.

GitHub Issue template

A valuable way to contribute to DEM is by providing feedback by creating issues:

• Bug report: We greatly appreciate reporting any instances of faulty behavior. Your bug reports help us identify and address issues promptly, improving the project's overall reliability.
• Documentation change request: We try to keep the documentation as clear as possible and up-to-date. We welcome and encourage requests for documentation clarification. Your input helps us maintain accessible and accurate resources for all users.
• Feature request: We value your innovative ideas for new features that could enhance DEM. Contributors are encouraged to share their feature requests, which contribute to the evolution and expansion of the project's capabilities.
• Report a security vulnerability: While we have been fortunate not to encounter any security vulnerabilities thus far, we understand the importance of a secure environment. To address this concern, we have configured an email address to receive potential security vulnerability reports. We also provide guidance on how to file vulnerability reports using GitHub's built-in function, should the need ever arise.

You can apply GitHub’s built in function to create issue templates.

Update the README

Adding another label in the repo's About section may not sufficiently capture the attention of visitors. A well-crafted README on the other hand immediately conveys that the project is actively participating in Hacktoberfest.
In the DEM repository, we've added a general Hacktoberfest introduction, complete with links to the Contribution Guideline and the XM community. This approach ensures that visitors to the repository are promptly informed about our participation in this event and have easy access to relevant resources.

Building a community: XM

Communication is key for every successful collaboration. Providing multiple channels for contributors to reach out to each other and the maintainers can speed up the onboarding and help them to fit in.

We set up 3 channels:

• Direct messages: We encourage contributors to reach out to us through direct messages on GitHub. Additionally, we have designated a specific email address that is actively monitored by all maintainers. This approach guarantees that contributors have accessible means to contact us directly for inquiries or assistance.
• GitHub Discussions: Leveraging GitHub's built-in functionality, we offer a Q&A-like interface through GitHub Discussions. This platform serves as an open space for discussions, where contributors can seek answers to their queries, share insights, and engage with fellow collaborators.
• The XM community: As part of axem's commitment to fostering an open and inclusive environment, we have established the XM community on Discord, dedicated to discussions related to embedded tooling and the ecosystem. Within this community, we have created a dedicated section, known as a Thread in Discord terminology, specifically tailored for Hacktoberfest discussions. This space provides a dynamic and real-time platform for contributors to connect, share ideas, and collaborate effectively.

Spreading the word

Nominating a repository in Hacktorberfest is as easy as adding the “hacktoberfest” or “hacktoberfest2023” topics in the About section. This way the repository will be visible when filtering for these topics, alongside the more than 133 thousand other ones matching the criteria… So standing out is quite difficult. Here are some tips that we found useful:

• Use the right labeling for your repository and the issues
• Share the repository in Hacktoberfest’s official Discord server
• Look for contributors in related communities

By implementing these strategies, you can increase your repository's visibility for potential contributors during Hacktoberfest.

Checklist

As we get ready for DEM's first Hacktoberfest, we've learned valuable tips for preparing an open-source project. These include clear guidelines, communication, and engagement.
For an overall project health check, you can use GitHub's "health checklist" found under Insights -> Community Standards. It helps assess our readiness and adherence to open-source best practices.

Summary

Hacktoberfest is a celebration of the global open-source community, and by opening our doors to contributions, we aim to give back to this incredible ecosystem while fostering a welcoming environment for newcomers.

Open source is about collaboration, knowledge sharing, and community building. By taking these steps, we hope to make our DEM project a rewarding experience for both seasoned contributors and newcomers. As we embark on this Hacktoberfest journey, we look forward to witnessing the positive impact of collective effort, innovative ideas, and the spirit of open source. Together, we can build a stronger, more vibrant open-source ecosystem for everyone.

Happy hacking!

Illustrations were used from hacktoberfest.com