How I improved Vue, and so can you

Do you have some experience with web development but don’t know how to start contributing to an open-source project?

That was me a few days ago. There are many resources on what to contribute to as first project. This piece of advice from Kent C. Dodds, for example, has stuck with me for a long time:

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
• which files to check first in a new JavaScript project and how to navigate in a big open-source repo
• how to run the vue-next unit tests
• about the package structure of vue-next

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.

Basic Setup

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:

git clone https://github.com/your-user-name/vue-next

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
git push

Start Learning

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.

Contributing Guide

The first things you should search for with your IDE are README.md files and a contributing guide.

The vue-next contributing guide will give you information about:

• the development setup and how to run tests
• the vue-next project 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

package.json

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.

Under the scripts section, you can find the development commands that we already saw in the contributing guide:

• build: compiles and bundles the typescript files with rollup into one JavaScript file
• 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.

The devDependencies reveal a project's tech stack. From this section, we can learn that vue-next uses typescript (as promised), rollup for bundling the files into a single entry point for the browser and lerna to manage the subrepos.

Project Structure

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 shared, compiler-core and 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 reactivity package.

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:

• computed
• effect
• reactive
• readonly
• ref

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?

The 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

Everything passed!

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-next because 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

Conclusion

In this article, you learned:

• how to get a high-level overview of an open-source project
• the new and improved package structure of vue-next
• how to make a pull-request, specifically for vue-next
• 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

Next Topics

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.