How I started contributing to opensource by opening my first pull request

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 when I found this awesome plugin 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 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

Wrong directory separator on Windows #2

nirebu posted on Jul 23, 2019

I was trying to use your plugin to autobuild the navbar and sidebar, but I found an issue while using the structure nav.foldername to build the navbar.

The plugin would build the $themeConfig.nav[].link as \nav.foldername\, thus breaking the navigation and sidebar loading.

I nailed down the cause to being on Windows, because the same config, run through a Linux VM works no problem, generating the parameters right as /nav.foldername/ both in the nav object and sidebar groups keys.

Is there a way to hardcode the correct browser separator to be / ?

Thank you very much

View on GitHub

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

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

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:

Adjusted the nav link separator to work also on Windows #3

nirebu posted on Jul 23, 2019

I'm proposing a solution to #2 which I opened. I used a normal replace to fix the Windows separator \ with the / character in the nav links.

View on GitHub

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.