Release 0.1: My First Open Source Experience
Foreword
Note: This section doesn't talk a lot about the code -- if you're looking specifically for that, skip ahead to the next section.
I've always wanted to get into open source development. It seemed like such a cool thing -- programmers from all over the world, working together to create something. Anything. I would browse through GitHub here and there, looking at all the neat things people were doing. Sometimes I'd think about joining in, but I'd always find some reason -- some excuse, really -- to stay away. I was too busy, I didn't know the language, there are already plenty of contributors, I don't know how to use Git, I don't know how to set things up... And so on.
Really, I was just finding a way to let myself off the hook and avoid confronting the real issue: I was afraid. I didn't want to make a mistake, I didn't want to make a fool of myself... And I really didn't think I had anything to offer. Logically, I knew that wasn't true; I do have a lot to offer. And yes, I'd probably make a mistake, but it wouldn't make me a laughingstock. People make mistakes all the time! It's no big deal, so long as you're open to admitting it, fixing it, and learning from it.
But logic doesn't mean much in the face of impostor syndrome.
The unfortunate thing about impostor syndrome, though, is that you're miserable no matter what you do. Push the bounds of your comfort zone? Get involved in something you've never done before? You'll feel like a fraud. Do nothing, and watch on from afar? You'll be constantly reminded of where you should be -- both presence-wise and skill-wise. You're stuck between a rock and a hard place, and the only way out is to buck up and resign yourself to feeling anxious... While you push the bounds of your comfort zone. If you're going to be miserable no matter what, why not be miserable doing the thing that'll most likely benefit you, right?
Here's the other thing about impostor syndrome: if you do the thing that most likely benefits you, you'll probably stop feeling terrible about it somewhere down the line. You'll get the hang of it. You'll figure it out. Impostor syndrome will still be there, lurking around every corner, but it won't be as bad as it was before (well, hopefully).
And that's what I did -- I bucked up and did what I had to do: refactor some code from filer to use const and let, instead of var. A pretty simple task, all in all; perfect for a newcomer like me. Between that, and my grades being on the line, I had all the incentive I needed to kick impostor syndrome to the curb and get started on what would be my first experience in open source development.
Getting Started
I started off by filing an issue and stating what I would do (refactor the code in a specific file to use strict mode, and replace var with const and let). I made sure that no one else was doing something similar by scanning the issues already present. Once I was certain no one else was refactoring filer/tests/spec/filer.buffer.spec.js, I went ahead and forked filer to my own repository. From there I cloned it to my machine, and created a new branch: issue-684, after the issue I had filed.
After that, I had to actually set up filer so I could run it and the related tests. This is where I made my first mistake: I didn't run npm install. The Contributing doc over on filer made it pretty clear that I needed to, but I still managed to miss that step. My bad. I tried running the tests, and of course they failed. I tried running eslint, and... Got nothing. That was the biggest indicator to me that I'd messed up; there had to be some errors for eslint to fix or find.
So I went back and looked over the docs, found npm install, and felt like an idiot. But hey, once I ran that command, everything started to work! What a surprise. eslint still wasn't actually returning any errors which I thought was odd (no errors? In my project files? What madness is this?), but I did get some errors out of the tests, which put my mind at ease. The first one I got while running npm run test:manual. It looked like this:
must honor the 'FORMAT' flag ‣
Error: global leak detected: triggerMblockEvent
at Runner.checkGlobals (mocha.947ba722.js:7351:27)
at Runner.
I checked issues on filer first, searching for anything with the keywords "triggerMblockEvent", "FORMAT flag", or "global leak", and got one result that seemed related. Upon closer inspection though, it was an entirely different issue -- and one that had already been fixed. With no other issues to look at, it was time to hit Google.
A post on StackOverflow informed me that this was an error that Mocha (one of the frameworks used to write tests for filer) throws this error when Mocha finds global variables -- aka, "var"s. It should be noted that filer is full of variables that use "var" -- that's why me and my classmates were sent off to refactor code for the project in the first place.
Armed with that knowledge, I now knew that there was nothing I could do about that error, unless I wanted to go through every single file and replace "var" with "let" and "const"... Which is a) not a small task and b) not within the scope of this project. So I let that error be, and moved on to the next test -- npm test. This is the command the project maintainers used, and the one the Travis CI uses to go over code that gets posted in pull requests. In other words, it's pretty important to pass these tests.
I didn't.
Or rather, I passed most of them, but then got hit with the following errors:
28 01 2019 14:08:41.263:WARN [launcher]: FirefoxHeadless have not captured in 60000 ms, killing.
28 01 2019 14:08:43.271:WARN [launcher]: FirefoxHeadless was not killed in 2000 ms, sending SIGKILL.
28 01 2019 14:08:45.274:WARN [launcher]: FirefoxHeadless was not killed by SIGKILL in 2000 ms, continuing.
On the brightside, it was an easy fix: install Firefox... Like outlined in filer's Contribute doc. On the downside, it was a bit of a blow to my pride. I suppose that's what you get when you don't read the instructions as carefully as you should. Lesson learned.
Getting to the Code
Refactoring the code was, hands-down, the easiest step. I opened up filer.buffer.spec.js in VSCode, and used CTRL+F to highlight every instance of "var". From there, it was a matter of scanning through the lot of them and seeing whether "const" or "let" would be more appropriate. I settled on "const" for the requires, since those should remain unchangeable. Everything else ended up being "let" since they should have been accessible only from the block they were declared in. After I was done, I checked and double-checked that I hadn't missed any stray "var"s somewhere in the file.
That didn't mark the end of my task, though. I wanted to be doubly sure that I remembered everything, so I went and looked through a few of the pull requests my classmates had made. I saw that some of them had forgot to add 'use strict' to the top of the file, and lo and behold, so had I. That seemed to be the only thing I was missing though, so with that, I made my commits. After pushing these changes to my branch, I made my pull request. This repository does a pretty neat thing where it actually gets the Travis CI to build your code and see if it will pass certain tests. It does take a bit to complete though, so while I waited for it to finish, I went and perused through the other pull requests.
I found this one, by a classmate of mine, which hadn't passed the build test. I took a look at the changes she'd made and noticed she was missing 'use strict' at the top of her file. She also had a few variables declared as "let" where they should have been "const" -- easy fixes. I pointed those out, and then made a mistake of my own. To check out her code, I copied her file to my local version, and ran the tests. VSCode threw out an error about a missing semi-colon on line 13, and I blindly trusted the editor to tell me what was right. Big mistake, because where I put a semi-colon, there should have been a comma. There was a comma, actually, I just overwrote it without thinking. Despite that semi-colon being wrong, I didn't get an error out of it, so I assumed that I'd done the right thing.
The owner of the pull request later pointed out my mistake to me. Another blow to the pride, and another lesson learned: look at the context before "fixing" a syntax error. The real error might be elsewhere.
After that, I went to check on my own pull request to find that it had failed some of the tests. I checked out the details of these failed tests, but couldn't really figure out what the issue was. One of them cited "etc/fonts/fonts.conf", a file that doesn't exist in filer (I did a very thorough search for it), and both of them had issues with the command "eval npm ci". I didn't know what that meant. I didn't know why things were failing, either; everything had worked perfectly, locally.
I'm still not 100% sure what the issue was, but I believe it had something to do with package-lock.json. This file was changed locally when I ran eslint, but I didn't let those changes get applied to my repository. Surely, it didn't need to be modified. Surely, things will work on their own. Well, they didn't, and once I uploaded the changed package-lock.json, things seemed to work.
Lessons Learned
I learned a lot from this project. Some were things I already knew, but never adhered to. Others I'd never even thought of. Here are the main three things I took away from this project:
Start Early: This one's a given, I think. You really need to give yourself ample time to work on these sorts of projects. A lot of things can go wrong -- and probably will go wrong -- and if you're working on a deadline, leaving everything 'til the last minute is a terrible idea. I didn't quite leave everything to the last second, but I should have started this a lot earlier than I did.
Read the Docs: Read them over, and over, and over. And when you think you've read the instructions enough, read them again one more time, just for good measure. I could have saved myself a fair bit of time if I'd done this -- I could've installed Firefox before the tests, or done an npm install right off the bat instead of forgetting about it. Reading will save you time... and minimize your frustration.
Read the Code: You'd think I'd have figured this out by now, with how long I've been coding, but don't blindly trust your IDE. If it says there's an error, definitely investigate, but don't remove the error from the context of the code. That's how more mistakes are made.
Comments
Post a Comment