Do you have some experience with web development but don’t know how to start contributing to an open-source project?
You contribute best to something you use regularly
This is all good and well. But I could not find many detailed guides on how people really started contributing. So today, I am going to tell you how I used Kent’s advice and show you how exactly I started my journey into open-source.
What’s in it for you?
In this article, you will learn:
- that you don’t need to be exceptionally smart or knowledgeable about a project to start contributing
- how to run the
- about the package structure of
Vue 3 Repo is Live
Evan You released vue-next on October 4th, to the public, which will be Vue 3 in the future. It’s currently in a pre-alpha stage, which means it’s not yet feature-complete. It‘s a faster, smaller, and more maintainable rewrite of the Vue framework in TypeScript. Because I love using Vue, I checked
vue-next out to learn about the new features more in-depth.
Little did I know that, in doing so, I was on the path to creating my very first open-source contribution.
Only people from the Vue team can submit pull-requests directly from the vue-next repository. Everybody else has to create a fork of the repository by clicking on the fork button in the GitHub GUI. By forking a project, you copy the project’s complete git history to your own GitHub account. You can then test it out, do some edits, and maybe submit a change request.
After creating a fork, I cloned it to my local machine to edit the source and use the more powerful search features of my trusted IDE:
Next, I added the original
vue-next repo as my upstream repository so that I could sync it with my repo if new changes are committed to the upstream repo.
git remote add upstream https://github.com/vuejs/vue-next.git
In case you want to sync new changes, just run following git commands on your fork’s master branch:
git pull upstream master
Instead of looking at code, in this blog post I want to focus on the high-level structure of the
vue-next repo to speed up further learning.
The first things you should search for with your IDE are README.md files and a contributing guide.
vue-next contributing guide will give you information about:
- the development setup and how to run tests
vue-nextproject structure and a high-level overview of the packages
- the pull request guidelines and how to format your commit
- how Lerna helps to manage all Vue packages in a monorepo
There are also smaller projects than Vue. These projects have only a small number of contributing people and because of that often don’t have a contributing guide. A helpful approach to find out more about the project is to look at the root package.json, which defines the development workflow and the tech stack.
scripts section, you can find the development commands that we already saw in the contributing guide:
- dev: watch all files and rebuild if they change
- lint: runs prettier over every TypeScript file
- test: runs the jest tests
You can also find out more about how
vue-next uses git-hooks with yorkie to lint your committed code and verify that you follow the commit message guidelines.
devDependencies reveal a project's tech stack. From this section, we can learn that
typescript (as promised),
rollup for bundling the files into a single entry point for the browser and
lerna to manage the subrepos.
At the time of writing, there are nine sub-packages in the
vue-next monorepo. Each such package also has one
package.json file, where internal dependencies are declared under the
dependencies section. Let’s chart the internal package dependency graph to have a look at the package structure:
Compared to Vue 2, the packages are much more modularized and can be installed independently in the future. One of the main reasons to do this was to enable easier development of native runtimes (iOS, Android, …). Such packages would just use the runtime-core abstraction to get basic reactivity as well as Vue lifecycle features, but then enhance them with native code. At the moment, there already exists the
runtime-test package. It is used to run tests without needing a browser-like environment.
Besides the dependency structure, we can also see packages marked with a blue background. These have no internal dependencies and should be a good starting point for learning.
Digging Deeper — Reactivity package
The packages without internal dependencies are the
reactivity package. The
shared package only contains basic functionality like
isObject which you could find in any project, so it wasn’t of much interest to me. The
compiler-core package has some external dependencies you need to understand first, and I didn’t want to dig that deep. So I started with the
To get a high-level overview of the
reactivity package, I looked at the package’s README file. Unfortunately, this didn’t provide much information about the concrete implementation of this package. Next, let’s look at the tests to collect more information:
Learning with Tests
The tests for the reactivity package are here. From the test names alone, we can gather that these are some of the core functionality you have to look at:
Some of them have already been published in the composition API RFC, which is a delightful read about Vue 3.
While further looking inside the tests, there it was: the code I could contribute to. Here is an excerpt of the
WeakSet.spec.ts as it used to be:
Can you spot the mistake?
WeakSet instance test does not test that it is an instance of
WeakSet, but instead only tests the normal
Set again. It is a simple copy & paste mistake.
How to contribute?
I didn’t expect to find something like this on my journey to learning Vue 3, and I wasn’t prepared for it. I didn’t know how to make a pull-request for an open-source repo where you do not have the master rights.
In case you don’t have much experience with git, this helpful resource explains the process with videos in great detail.
For my specific case, I created a new branch:
git checkout -b test/reactivity-collections
There I corrected the test. Afterwards, I made sure that there weren’t more copy & paste mistakes in the other tests. As it turns out, there was another one:
I reran the tests (only for the reactivity package because I only fixed tests there):
yarn test reactivity
Now I tried to commit my work:
git commit -am "fixed a small copy & paste mistake in the reactivity/collections tests"
Oh no, what happened? A quite frightening error message was presented to me:
ERROR invalid commit message format.
Proper commit message format is required for automated changelog generation. Examples:feat(compiler): add ‘comments’ option
fix(v-model): handle events on blur (close #28)See .github/commit-convention.md for more details.
You can also use npm run commit to interactively generate a commit message.
This was the
vue-next commit-msg hook at work: it didn’t validate my commit message because it did not follow the commit conventions.
I quickly fixed this and committed again:
git commit -am "test(reactivity): fixed small copy & paste error"
git push -u origin test/reactivity-collections
Back in GitHub, its GUI immediately asked me if I wanted to submit this change as a pull request to the main
vue-next project. And so I did just that. After their CI-pipeline and a person called znck (a member of the Vue team) validated my changes, it was merged after a few hours by Evan You.
It wasn’t as difficult as I expected, and I hope to contribute more while learning more about Vue. Now it‘s your turn!
“But I do not have enough experience to contribute!”
First of all, there are many things an outsider of a project is even more suited to discovering than the insiders themselves: Missing tests, weird code constructs, misleading comments, …
Here are some more ideas to start learning about, and possibly contributing to, a new project:
- try to understand tests and think of edge cases they do not yet cover
- read the code and documentation — you will probably find small things that are easy to improve
- try to find out the root cause of reported issues (not yet relevant for
vue-nextbecause they have not enabled issue-tracking for now)
- sharing things you learned with the community
If you need more guidance on how to contribute to open-source, check out these articles:
- an article by Kent C. Dodds where he also talks about his first open-source contribution
- a small tip from Dan Abramov: Just “watch” all GitHub activity for
vue-next(top right corner in the GUI)
- a comprehensive guide on why and how to contribute
In this article, you learned:
- how to get a high-level overview of an open-source project
- the new and improved package structure of
- how to make a pull-request, specifically for
- that no contribution is too small
- that learning about your favorite open-source software is a good way to get started with open-source contributions
The next blog post will be a bit more technical. We will dive more deeply into the new
reactivity package and learn more about ES6 Proxies, Symbols, and WeakMaps.