Building Open Communities with GitHub

TLDR;

In this article I share my experience and ideas on how to build open communities. I've been working on this concept and tooling to piece things together for community automation and I hope this can help you and your community to make things easier.

Motivation and Introduction

Communities are hard. They are hard to build, hard to maintain, and hard to grow. But, building communities has been one of the most rewarding things in my career, because I met so many amazing people and was forced to learn and do things out of my comfort zone.

I remember over 10 years ago I attended my first small tech conference - CouchConf in Berlin. Luckily there was a BerlinJS Meetup happening around the same time and I was blown away by the community and the people. They have a GitHub repository set up for the website and talks are submitted as GitHub Issues. I was amazed by the simplicity and transparency of the process, so I forked the repo and founded BarcelonaJS a few weeks later. This was the start of my own organizers' journey.

A little anecdote of a regular and very frustrating experience: You spent hours preparing, communicating, finding and inviting speakers, finding and securing a date & venue, talking to sponsors for food and drinks all to put together a great event. And when the time comes you're sitting there alone or with a fraction of the people you thought would come, because Meetup says "150 people RSVPed YES". And in one rare occasion that was just bad luck with the weather, but more often when I talked to people afterward I heard this:

This is amazing, I wish I'd been there, but I did not know!

This phrase was the motivation for me to start exploring GitHub as a community tool because GitHub is one of the most amazing platforms for automation and that's what you need to do as an organizer: automate the crap out of everything to publish the event on Eventbrite, Meetup, Twitter, Facebook, Telegram Groups, WhatsApp, Email, Calendar, etc. etc. etc. and do that 2 weeks before, 1 week before, 3 days before, 1 day before, 1 hour before the event so nobody can say afterward: "I did not know about this". Because in the end, you're not doing this for yourself but for the community.

During my travels, I came across Node.js and JavaScript communities on Meetup with thousands of members, but not a single upcoming or recent event. This can happen for many reasons, but it's often because the organizers do not have time or have moved on to other things, and it's hard to find a successor to keep things running. Meetup and other platforms are great for the discovery of communities and events, but they make it hard for members to reach out to the community in case an organizer is no longer active and to take over / revive the community.

As a developer, I spend a lot of time on GitHub and am familiar with the tools and workflows, so I started exploring on how to use GitHub as a community platform.

Benefits of using GitHub for Community Building

Open Source & Open Community

The first and most obvious benefit is that public repositories on GitHub are Open Source. This means all the content, issues, and discussions are public and can be forked, copied, and reused by anyone. This is great for communities because it means that if the community is abandoned, anyone can fork it and continue the work. It also means that if you want to start a new community, you can fork an existing one and adapt it to your needs.

GitHub has user/team/organization management built in, so you don't need to build anything yourself. It's easy to invite someone into the organization or to add teams with different permissions of the organization.

Most of us know how to use GitHub and visit the site on a daily basis, so there's no need to bookmark additional sites for database administration, content management or other tools. With GitHub Actions, we can run automated tasks on a schedule or on demand, and with GitHub Pages we can host our community website for free.

Building in Public & Transparency

For me, one of the most important benefits of building a community on GitHub is full transparency and open communication. Everything[1] is public, so there's no need to worry about who has access to what. This means that anyone can contribute to the community, and anyone can see what's going on. This is great for building trust and for building a community that is inclusive and welcoming to everyone.

My aim with communities like BarcelonaJS, CDC etc. was/is to create free and open spaces for developers to share and connect. And "free" is where transparency comes in. In the past, I always kept my hands off financial contributions. If a company wanted to sponsor, they could order food or drinks directly to the venue, but I wouldn't facilitate. Thanks to the Open Collective, this has become much easier and we're now able to accept financial contributions and make them transparent to the community. These are used for example to pay for the domain(s), to get food and drinks, run ad campaigns etc.

[1] of course, you can also create a private repo for internal organizers discussions etc.

Drawbacks & Caveats

GitHub is not a Community/Event Platform like Meetup, so there are some caveats. I've grown used to treating Issues as "Events" or "Talk Proposals" and GitHub Issue Forms to structure submissions. But it's not ideal and takes time for newcomers to understand "Create an issue to submit a talk". There are no "comfort features" to pick a date, location on a map, etc. and trigger a simple email notification to hundreds of people.

The Open (Developer) Community

This entire concept is primarily focusing on developers and engineers, as it evolves around GitHub and IssueOps. To give an idea of my previous experience, here are a few communities and conferences I've helped build:

• BarcelonaJS, 2012 - 2018
• Hackers & Founders Barcelona, 2012 - 2015
• Node.js Barcelona Meetup Group, 2012 - 2018
• Couchbase Barcelona Meetup, 2012 - 2015
• NodeConf Barcelona, 2015, 2016, 2017
• MediterráneaJS, 2015
• CyprusJS 2018 - 2021
• Cyprus Developer Community 2020 - present

While building these, I've continuously worked on a set of tools, workflows and automation to make the lives of organizers easier, because it's such a tough and often thankless job. So here's my Open Community Concept of how I construct a public community on GitHub.

Labels & Structure

The first step is to set up a GitHub organization and create two repositories:

1. events
2. talks

The names are obvious: in the events repository are templates for creating new events, and in the talks repository are templates for submitting talk proposals. Talks can be linked to events to build up an agenda and, if you manage to get engagement from the community (remember: it's hard!), comments and reactions such as :thumbs-up: or :heart: can be used to vote on talks.

You can also use a GitHub Project to manage the event lifecycle through the proposal, scheduling and announcement phases:

In Cyprus, we added labels for the different regions on the island, but most importantly an "Approved" label is needed. All new issues are created with the "Event" label, but only someone with "triage" permission (organizers team) can "approve" the event. This is important to avoid spam and to make sure the event is relevant.

Now that there's an organization, some repos with issues and some structure in place, it's time to automate.

GitEvents

GitEvents / GitEvents on GitHub goes way back (2014) and started with the name gitup as a collaboration "hack weekend" between the London Node User Group (LNUG) and the Barccelona Node.js Group. Back then, GitHub Actions didn't exist and we tried to use Webhooks for issues to build up structured data for GitHub Hosted websites based on Meetup.com data. The setup was cumbersome and the project was abandoned for a while.

Today, GitEvents is a simple set of GitHub Actions to automate issue workflows. "Git Ops" for meetups and events. All that's needed is a GitHub Organization and a GitHub App. Some of the features are:

• Inclusive Org: Any interaction with GitHub repositories, issues or discussions triggers a workflow to invite the user to the GitHub organization and adds them to the "Community Members" team. The permissions are the same as for the public, but a little "growth & engagement hack" is that you can @-mention all community members in issues. This is great for announcements, but shouldn't be abused, otherwise you quickly lose members.
• Issue Templates: I put together a set of simple templates for events, talks, code of conduct replies etc. to quickly get started with GitEvents.
• Broadcast: are re-usable GitHub Workflows to automate marketing and common tasks such as emailing/tweeting/blueskying members, creating/updating events on Discord, EventBrite, Meetup etc.
• ICS: is a GitHub Action to generate iCal files for events. iCal is a standard for calendar events. People can just add this as a subscription to their calendar to keep up to date with community events. We created a redirect to the github file, so people can subscribe to the calendar with a simple link: https://calendar.cdc.cy.

Everything is "plug and play" so you can pick the Actions you like and it's relatively easy to compose them into a workflow. For examples, check out the Cyprus Developer Community Workflows.

If you'd like to get started with GitEvents and need some help, please reach out on our Discord Server GitEvents is a work in progress and there's always a lot to do especially with integrations to other platforms etc. If you want to help, please get in touch.

GitHub Issue Forms

Issue Forms are still a relatively little-known feature on GitHub. Instead of a regular Markdown templates, a YAML file can be provided with a form configuration.

This is pretty cool to get structured input, but once saved as "Issue", the data is semantically useless because it's just Markdown. I've experimented with Milestones, Markdown headers, Labels etc. to add semantic information like dates, locations etc. to an issue, but nothing worked well. So I started building GitHub Issue Forms Body Parser. This helps to parse an issue that was created through a form to extract dates, links, images, lists etc. and convert them into structured JSON data. This can directly be passed on to other platforms like Discord, EventBrite, Meetup, etc. or used in mailings, tweets etc.

The Issue Forms Body Parser is also available on npm as a library to parse any Markdown text. Only recently I realized entire README.md files can be parsed for structuring data for a website:

query ($organization: String!, $repository: String!) {
  repository(owner: $organization, name: $repository) {
    id
    name
    object(expression: "main:README.md") {
      ... on Blob {
        text
      }
    }
  }
}

This is the query to retrieve file content from the main branch of a repository, and you can pass that into the "body parser":

const structuredData = await bodyParser(readmeFile()?.repository.object.text)

Instead of keeping yet another copy of your community description, you can now fetch the About section from the README.md file and use it on your website.

GraphQL API

With the latest https://cdc.cy website I wanted to explore and push the boundaries of what's possible with Issues, README.md files and structured JSON data and I'm fairly pleased with the result:

• most of the website content is fetched from README.md or .json files on GitHub; everyone can edit, no CMS or account etc. required
• upcoming and past events are based on GitHub issues (approved & event-labelled issues on the events repo)
• organizers are fetched from GitHub Team Members
• Events can be annotated/enhanced with proper location data from a "common locations" file
• Speaker profiles are entirely based on GitHub User Profiles, we can fetch avatars, bio (readme), location, etc. and build pretty speaker profile pages
• We can display some stats such as "number of members of the organization", "number of past/upcoming events" etc.

All of these features were possible through the GraphQL API and by parsing the Markdown files with the body parser.

Summary & Outlook

I've been working on this concept for a while and it's still changing shape every once in a while. But the basic ideas I've adopted from BerlinJS haven't changed:

• Open Community: everything is public and transparent, and everyone is welcome (as long as they follow the Code of Conduct)
• Events and Talks/Proposals are issues in a repository
• Labels help with structure and automation

Building all of this has taken a lot of time and energy and there are still lots of things missing I don't have time for:

• proper email integration with schedules, reminders, etc.
• finalize EventBrite integration
• add Meetup integration
• add WhatsApp/Telegram/Slack integration
• improve issue handling, and automatic comments (ie. Code of Conduct reminder, follow-up reminder etc.)

If you think this can help you and your community and want to get involved in piecing the puzzle together, please reach out on the gitevents Discord Server, on GitHub Discussions or directly on one of the GitHub Issues.

If you're in Cyprus or Barcelona, please join and support the local developer groups.

Random Organizers Thoughts, Tips & Tricks from personal experience

• Venues: picking a company office as a venue is easy, but has lots of drawbacks. It's easy to manipulate people once you have them in the office (look at our cool place, we even have a cocktail bar!). Remember the company has different motives than you (recruiting, marketing, etc.). Sometimes there may even be conflicts, that people aren't allowed to visit the competitors' office. If possible, I prefer "neutral" co-working and event spaces and thanks to Open Collective you can get sponsorships to pay for the venue with fair (recruiting/marketing/etc) rules for everyone.
• Reminders: we're all busy and it's easy to forget things. Not everyone is as engaged, motivated & psyched about the event as you are, so regular reminders keep people engaged and help to build a habit. Find a good cadence for reminders, and do not overdo it and spam people. Different media work for different people, so I try to cover as many as possible.
• Scarcity "I've noticed that announcing the event just one week before it's happening and having a limited amount of seats works better then releasing month in advance with 100+ capacity" – Dmitry Zaets, BarcelonaJs
• Perks: "Giveaways are fun, and giving away tickets to conferences and other stuff can be nice perks for attending" – Dmitry Zaets, BarcelonaJs
• Consistency: "Establish a realistic schedule from the outset. Whether it's a monthly meetup or a quarterly conference, consistency is key. Create a roadmap, allocate responsibilities, and stick to the plan. This not only keeps your audience engaged but also helps in building a reliable community." – Federico Rampazzo, CDC.cy
• Finding Speakers: "Don't be afraid to approach experts who might be willing to share their insights. A lot of your members are likely to have interesting stories worth sharing! It can be an enriching experience for them as much as for the community. Taking photos, videos, audio recording of the events is valuable and help the speakers in their speaking career, as well as increasing the reach of the event." – Federico Rampazzo, CDC.cy