Greetings! 👋 My name is Kylee, I'm a technical community manager, working in open-source software since 2021. Recently, I was accepted into GitHub's first Open-Source Community Management Program for Digital Public Goods. During this program, I maintained a non-profit's repos for Hacktober Fest 2023, while under the mentorship of GitHub community managers. Here, I share a list of helpful techniques I've learned along the way, from beginner guidance to "ah-ha moment" tips!
Being an open-source maintainer comes with DIVERSE responsibilities.
From project management, troubleshooting and triaging, dependency management, building automations, CI/CD, git ops, and ensuring the overall health of the project.
Ultimately, maintainers need to wear many hats. In this guide, I'll share 5 key techniques to help streamline this highly-faceted workflow.
Follow D.R.Y. (Don't Repeat Yourself) Principles:
As a GitHub maintainer, you will encounter countless repetitive tasks. Here is how to save time:
- The CODEOWNERS File: If you are frequently tagging the same code reviewers for changes to the same files, consider a CODEOWNERS file to define code ownership within a repository. CODEOWNERS can automate assignment of code reviewers, ensuring that the appropriate individuals are notified when changes are proposed in their designated areas. It's simple to set-up, check out the GitHub docs to get started: GitHub Docs: About code owners.
- Default Community Health Files: Instead of managing multiple community health files for every repository (such as the CODE_OF_CONDUCT, LICENSE, and CONTRIBUTING files), create default community health files that are shared by all repos in an organization. Learn more: GitHub Docs: Creating a Default Community Health File.
- Organization-level Repository Settings: In organization-level settings, you can save time by managing multiple repos in one place, such as their default issue labels, repo tags, and rulesets.
- Automations: Automate routine tasks, like commenting helpful information, labeling, running linters, and more with GitHub Actions. Here's a simple yet effective example of leveraging GitHub Actions as a maintainer: automating helpful messages to contributors upon issue assignment. See it in action here. Discover GitHub Actions: GitHub Docs: GitHub Actions.
- Templates: Enforce consistency using templates for creating issues, pull requests, contribution guidelines, and bug reports. My favorite template is the pull request template, which includes code review checklists to free maintainers from having to repetitively remind contributors, so we can focus more on giving effective feedback. See a pull request template here. Get started with GitHub templates: GitHub Docs: Configuring Issue Templates for Your Repository.
Be Data-Driven:
Data-driven metrics are built into GitHub and can be further extended with the GitHub API. When you make the most of GitHub's features, you can build a suit of data points to automatically track contributor and project progress, and even visualize it:
- GitHub Project Boards: GitHub is developing new features and ongoing support for native project management within GitHub. These project boards provide linkage between your tasks and contribution activity, along with automated insights. Learn more about Project Insights: GitHub Docs: About Insights for Projects.
- Repository Graphs: Leverage repository graphs in the Insight tab of your repository, where GitHub automates data visualization for various activity stats like contributor activity, traffic, code frequency and more. Discover GitHub's Repository Graphs here: GitHub Docs: About Repository Graphs.
- GitHub API: Utilize the GitHub API to visualize repository data for customized use cases, such as gathering real-time insights, pulling repository data, identifying contribution patterns for research, and monitoring activity. Check out this guide on data visualization with the GitHub API: GitHub Docs: Rendering Data as Graphs.
- Labels: Leverage labels as data points for activity analysis. Typically, you use labels to describe the effort (time requirement / complexity), context, and state of the issue. But they should always be simplistic and sane to remain user-friendly. I recommend this guide by Sean Trane for an overview of smart issue labeling: GitHub Labels that are logical, colorful and sensible by Sean Trane.
- Milestones: Visualize progress by setting up milestones. Milestones provide a simple method to group and organize related issues and pull requests, making it easier to set goals, assign tasks, and prioritize work.
Optimize Resources for Consistency:
In an ideal world, maintainers are online 24/7 to engage with contributors. But when I maintained repositories for a global social impact non-profit, resources were limited, so I had to develop processes to optimize for community engagement with what we had:
- Schedules: Create a schedule for checking-in with contributors and share it on public channels and social media. You can also notify contributors of maintainer’s schedules in automated messages on pull requests using GitHub Actions.
- Notifications: There are multiple methods for setting up GitHub notifications, I recommend finding a method that works best for you. You can integrate GitHub notifications with Slack, Microsoft Teams, and other platforms you see here: GitHub's Integrations Dashboard, or configure RSS feeds if you're daring. Get started here: GitHub Docs: Configure Notifications.
- Delegation: As a maintainer, it's helpful to think like a project / program manager. Your work should scale horizontally and vertically as the community grows. By delegating tasks effectively, community engagement can be sustained, even when critical issues arise. I found this guide by Asana to be helpful: Asana Blog: Prioritize Tasks in 4 Steps.
Be Detail-Oriented:
Maintainers have diverse responsibilities that we must effectively manage in order to offset the negative impacts of frequent context-switching. Constant context-switching (or multi-tasking) has shown to cost up to 40% of your productivity and result in missing finer details. Fortunately, there are methods to staying productive in "maintainer madness":
- Time-Blocking: Use time blocking for separating distinct tasks from another. In result, this helps you acknowledge when you are context-switching, which develops self-awareness of the specific requirements for accurately completing each task. I found this blog post by Asana to be helpful for this: Asana Blog: Context Switching is Killing Your Productivity.
- Stay in Your Scope: Understand your scope and objective as a maintainer. Maintainers are supposed to create more GitHub issues than they solve. Instead of trying to solve everything, focus on your main responsibilities, such as managing contributions and GitHub Actions, and leave the issue solving to the dev team and community.
- Checklists: Create checklists for routine processes to ensure all necessary steps are completed, such as merging pull requests or creating issues. It is easy to overlook important details while completing many small steps within a larger task. Check out this example of a pull request checklist for maintainers: Pull Request Checklist Example.
- Seek Feedback: Continuously seek feedback for external review of your work. By regularly communicating with your team, you foster an iterative and collaborative culture that promotes continuous improvement, and helps maintainers stay accountable for the quality and consistency of their work. Contributors also provide valuable insight, so create a feedback process with GitHub issues or by linking to a feedback form.
Prioritize Security & Compliance First:
Ensuring the security and compliance is of utmost importance, even if you are not a cybersecurity specialist. A basic understanding of maintaining safe and secure GitHub repositories is essential for your project’s success:
- Dependency Management: Prevent security vulnerabilities by following dependency best practices. This includes leveraging security scanners (like Dependabot or another tool, however Dependabot is the only scanner native to GitHub) to automatically check for and update outdated dependencies. You should set-up continuous dependency scanners (ie: trigger scans upon pull request and periodically), enable alerting to receive notifications about security vulnerabilities, and regularly review dependencies for the latest security patches.
- Permissions and Secrets: When managing permissions, GitHub maintainers should always follow the principle of least privilege, meaning only granting the necessary permissions to workflows and actions, and nothing more. Create teams for core developers and set branch permissions for each repo. At minimum, make sure to enable two-factor authentication for all staff. Keep secrets (such as API keys) safe by never hardcoding them in workflows, using GitHub secrets, regularly reviewing and rotating secrets, and monitoring secrets for unauthorized usage.
- Policies and Security Guidelines: Equip your GitHub with a security policy using a SECURITY.md file. Ensure that this policy clearly describes directions for privately reporting a security vulnerability, and that you will be alerted when vulnerabilities are reported. Similarly, you should include a Code of Conduct using a CODE_OF_CONDUCT.md file with a clear violation reporting process to enforce safe community standards. Lastly, you should prioritize legal compliance if necessary, such as including a Privacy Policy on the applications website, credit for images used, and any other legal compliance policies.
Further Reading -- Security & Compliance Guides:
Summary & Final Thoughts
As a GitHub maintainer, following these 5 techniques will help you succeed:
- Follow D.R.Y. (Don't Repeat Yourself) Principles:
- Be Data-Driven
- Optimize for Consistency
- Be Detailed-Oriented
- Prioritize Security & Compliance First
