Easy Open Source - Orchestrating the Open Source Contribution Workflow

This article was published on Thursday, April 22, 2021 by Vignesh T.V. @ The Guild Blog

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:

• GraphQL Code Generator
• GraphQL Mesh
• GraphQL Tools
• GraphQL Modules
• Apollo Angular
• GraphQL CLI
• GraphQL Config
• SOFA
• GraphQL-ESLint
• GraphQL Inspector
• GraphQL Hive

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.