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.
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.
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.
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.
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:
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.
The first step is to set up a GitHub organization and create two repositories:
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 👍 or ❤️ 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 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:
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.
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.
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:
README.md
or .json
files on GitHub; everyone can edit, no CMS or account etc. requiredevents
repo)
All of these features were possible through the GraphQL API and by parsing the Markdown files with the body parser.
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:
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:
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.