How I started contributing to opensource by opening my first pull request
Tags: opensource, github, beginners, vue
Published: 2019-08-14 14:35:08

and it was easier than expected. Like, really damn easier than expected.

## The problem

I wanted to build a *zero-or-almost-zero-config* documentation system to use at our office to move away from a hell of ODT, PDF files scattered around a file server. You know what I'm talking about 😁

Long story short, I've settled on [Vuepress](https://v1.vuepress.vuejs.org/) when I found this [awesome plugin](https://github.com/ozum/vuepress-bar) to auto generate the sidebar and the navbar based on the directory structure: I think that the approach of **convention over configuration** is one of the strongest and easiest, especially if you want the team to be able to write docs from the get go.

During the testing phase I've noticed a strange behaviour when navigating in different sections (in Vuepress lingo: the top bar), as defined by the directories with the `nav.directory` name: every link there would result in a 404.

Have you ever experienced the moment in which you say to yourself

> Is it possible that even following the docs/guide/tutorial to the last paragraph, I cannot replicate the awesome result the author presented? 

Been there? I've been there a lot, but this time I thought I could dig into it, and maybe help in fixing a problem so others wouldn't have to go through this hurdle.

## Debugging Vuepress

The first evidence I found that put me on track was seeing that the link destination for the links in the navbar were malformed or just plain wrong, not prepending the base URL and with the page name missing:

```
# rendered href
https://nav.directory/.html

# desired href
http://localhost:3000/nav.directory/index.html
```

I hopped in the awesome [Vue Dev Tools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd) and started digging in the Vue component props created by the dev server and noticed that the `$site.themeConfig.navbar` and `$site.themeConfig.sidebar` parameters, generated by the `vuepress-bar` plugin had malformed values, like:

```
"sidebar" : {
  "/": {...},
  "\nav.directory\": {...},
  "\nav.directory2\": {...}
}
```

The `backslash` characters put me on the right track, because that's what Windows uses as a directory separator by default. To dissipate any shade of doubt I tried the same exact config inside a Linux Docker container and actually it worked as expected.

## Opening the issue

Identified the possible cause, I went to the `vuepress-bar` Github repo and opened this issue.

The process is pretty straightforward:

- Selected the issues tab
- Made sure that no one else already filed the same problem (not many Windows users these days I guess)
- Clicked the `New issue` button
- Tried to be as descriptive as possible but concise at the same time to not waste the developer's time, including examples of the rendered html and the desired result

{% github https://github.com/ozum/vuepress-bar/issues/2 %}

## Finding a possible solution

Digging inside the actual plugin folder in `node_modules/vuepress-bar` and after a few minutes of reading someone else's code, who is way more experienced than me, I finally got to the *offending* line.

Three attempts later and testing with a few different configs, I finally settled on a solution, which is probably quick and dirty, but at least appears to fix the problem.

## Proposing my fix by making the pull request

To propose the author my changes, I needed first to fork the repository by clicking the `fork` button at the top of the repo. Next, I cloned it locally via the command

```bash
git clone https://github.com/nirebu/vuepress-bar
```

Opened the folder in VS Code and made the same changes I made inside the `node_modules` and pushed the change to my forked repo using these commands

```bash
git add . # to add all the files changed, in this case just one
git commit -m "Adjusted the nav link separator on Windows" # to describe what my change would do if applied
git push origin master # to actually upload my changes to my forked repository
```

Now it was only a matter of opening the actual pull request, to notify the author about my change. To do so, I clicked the `Pull requests` button in the repository navigation bar and next the `New Pull Request`.

To select my repository as a source of changes I needed to select the `Compare across forks` link, and then it was as easy as selecting the `HEAD` commit (the most up to date) of my forked repository `master` branch. The result was this:

{% github https://github.com/ozum/vuepress-bar/pull/3 %}

Phew, done.

Now let's wait for the author to review and approve, comment or reject my pull request right away.

## Closing thoughts

Contributing to someone else's project can be a daunting process because, apart from the technical aspects, there are plenty of psychological factors involved like impostor syndrome and fear of rejection.

I'm sure my proposal isn't the best one or the most elegant, but at least I've overcome the initial wall and tried. When I'll become more proficient in my programming skills I'll make sure to contribute even more to other people's projects: it's a way of giving back to a community that alredy have given me much.