Easy Open Source - Orchestrating the Open Source Contribution Workflow

Vignesh T.V.Thursday, Apr 22nd 2021

Announcing GraphQL Hive, the complete GraphQL API manager

TL;DR

We released The Guild’s contributor guide
Contributor workflow
Video tutorials on how to contribute
The Guild’s tooling for maintaining open source libraries
A new system for managing our repositories (Process based labeling system, issue templates)

Open source has revolutionized the way we build, collaborate and release software and there are definitely a lot of instances where the community of contributors and maintainers have taken the lead to make the projects thrive in the ecosystem and this is really exciting to see. Making open source more approachable is beneficial for the maintainers, users and the contributors themselves thereby opening new paths for them that seemed harder before. And our strong belief is that contributing to open source shouldn’t be hard!

Orchestrating the Open Source Contribution Workflow

But as anything goes, it is not without its own set of challenges. The number of open source contributors is a tiny fracture compared to the number of users of our libraries.

This advocates us to think of interesting solutions, as we believe many developers are missing out on these opportunities to advance themselves and their careers.

”We see that as The Guild’s core mission!”

After maintaining a huge list of growing open source projects over time being actively used by the community, we, The Guild had quickly come to a realization that we really need a way to standardize our workflows considering everything we do in open source is modular and componentized thus increasing the complexity of managing these projects.

We wanted to share and “open source” our workflows so others could join us in this journey and benefit, thereby making contributing more accessible for people.

To give you an insight, these are some projects which we currently manage as individual contributors:

As you can see, the list goes on (for a good reason), and we have more interesting projects on the way which you can find here 😉

And some major things which we were looking to do were to:

Empowering first contributors - Provide a great experience for beginners who want to contribute to any of these projects
Give the maintainers an eagle eye view of all the projects and things to do to progress to the next steps
Provide a level of standardization in the contribution/development workflow of all these projects so that we don’t have to re-invent the wheel every time, but rather spend time on the important stuff
Create a framework of sorts which works not only for the projects we work on in The Guild, but something which can work for other open source projects as well.

This led us to the creation of the contributor workflow guide to help us standardize the workflow, guide beginners who would like to contribute and also act as a guide for other open source projects who are looking at a similar standardization approach (What we have is an initial iteration of the guide and there is definitely a lot of room for improvement. If you have any suggestions, do let us know - we are all ears 🙂)

But does creating a guide suffice to achieve our goal? As you guessed, definitely not, and the guide was just a start to an amazing journey ahead.

Then we started thinking about the next important thing which we can address to make both maintainer’s and contributor’s lives easier - LABELS

Process Based GitHub Labels

As simple as this feature may seem, labels/tags are the most important feature in any project management tool, in this case GitHub because it gives us the ability to track the progress, the next steps to be done and also communicate the same to various stakeholders, be it the maintainer or the collaborator. Not just this, it can also act as a great way to onboard new collaborators who are interested in contributing to the project.

But you may wonder, labels are an already available feature of GitHub, what more can we do with it?

The problem in our case is that considering every project had its own repository (as it should be) and everything evolved over time, we had different way of tracking issues in different projects, and we followed our own sweet conventions and while this did the job for us when we started off this started getting complicated with more and more projects getting added to our portfolio every month.

This is when we strongly felt the need to sync/orchestrate labels across all the repositories while also respecting the differences between the projects (one size may not fit all). This led us to a proof of concept with different label syncing tools and after quite a bit of analysis, we landed on Label Syncer to manage both master and repository level declarative labels (If someone from GitHub is reading this, maybe this should be an inbuilt feature 😇)

Doing this was pretty simple. You can find the repo here which is used as the master repository to push all the labels downstream, and we still retain the repo specific labels in their own repository (like this)

Now that a technical proof of concept was complete, the next question we had was “What labels should we standardize on as the master labels?”

Now, Urigo had an interesting thought process - since we had already published the contributor workflow guide, why not we label issues keeping the same in mind? All we needed to do was push an issue towards progress from Step 1 to Step N

The goal here was to make it more obvious to anyone who arrives to an issue where exactly it stands and most importantly, what can you do to help advance the solution.

Now, this is when we started putting labels against different stages in the workflow guide standardizing on stages like this to start with:

stage/0-issue-prerequisites
stage/1-reproduction
stage/2-failing-test
stage/3-local-solution
stage/4-pull-request
stage/5-alpha-release-testing
stage/6-released

which is how most workflows look like for every project (Guild or even otherwise) - This is again the initial iteration, and we will have more room for improvement over time, and you may see more/lesser stages over time.

The next thing we did was to prepare a set of standard issue templates which remains almost the same across all our repositories. Again, a work in progress we will tweak this as the need arises. This gives us an ability to suggest a standard template to file issues and PRs to all the new contributors asking for all the important details like the environment and version they use, possible reproductions/screenshots, additional context and also providing them with checklists to be actioned upon when filing an issue.

While all this might seem very simple, doing this has a long term benefit of communicating your expectations as a maintainer to the community when they are looking to contribute. Now, this is something which some projects tend to ignore.

This journey has not concluded yet, and the next thing which we will be doing is labelling all the issues in all the repositories we manage appropriately against these stages which can give a better sense to both the maintainers and the contributors avoiding any ambiguity in the process.

Now, these are just some ways in which we are looking at streamlining open source contributions and make the projects thrive in addition to providing great docs, great test coverage, active maintainership among other things, but we are also exploring other ways which we can use (if you have any tips, do let us know 🙂)

Our intention is not just to keep all this to ourselves but also help other open source projects and the maintainers by sharing our thought process and hence this blog. If we find some other tips along the way, we will make it a point to update this blog - so, do watch out for that 😉

See you all soon in our next blog.