The Initial Contribution

“Find your piece to add.”

What I’m Learning

Just want to let you know I’m going to try to focus on my process, and not too much on what was done technically. I’m basically writing about how I’ve come about my first contribution to an open source project.

Disclaimer: This is my first (very small) contribution to an open source project. I doubt it’ll be this easy moving forward with finding an issue and having a pull request accepted. Also, I don’t know why I’m using the Git desktop application over CLI, haha.

Finding an Issue

I would probably say this would be the hardest portion of contribution. While you can just look through the issues and request to be assigned it (easy way out), the hard part would probably be finding one yourself.

Luckily, the project filerjs had a recent pull request for supporting promises (asynchronous version of the functions). This made things a lot easier to find an issue. With large projects like these, there’s going to be tests written to ensure that the functions are behaving as expected. That said, the tests weren’t written for these new functions added, so now to complete the task, I just had to find a test to write.

This would become the “harder” part. With so many people trying to make a contribution, a bunch of issues are being made! I had to browse through the issues and try to find a test to write that someone hasn’t already requested and create my issue.

When you hit the issue tab, top right has “Create new Issue” which brings you here.

While we wait for approval of the issue and assignment, I start setting up to actually implement and test code.

Get the Code Working

We start with making a fork of the code (taking a copy for ourselves).

Click fork and add it once you’ve reached the repository you’d like to work on.

After we’ve got a copy, we got to make sure we can make changes with out making trouble for others, thus we copy the code locally make our own branch (It was named after the issue, so Issue-444 — Notice how I’ve made a duplicate issue, this is bad. Make sure you don’t make dupes, haha) and switch to it.

Now that we have our own copy, we got to figure out how to play with it. Looking at the readme.md, they have a link for those who want to contribute (I assume most bigger projects will have this). This gives the information we need to get started.

With Node.js installed, we navigate to the filer directory and start to follow the instructions in cmd.exe:

• Run npm install to get the dependencies
• From the command line, I ran npm run lint:fix next (Fixes a spacing issue since I’m running on Windows)
• Next I run the tests npm test to make sure everything works (I tried testing before the previous step and I was getting issues with spacing, so I listed fixing first before testing, haha)

By this point I believe I was assigned the issue, and with the working code base, I began working on the issue.

The Fix

Now, like I said before, this was an easy issue. With this new way of executing the functions (promises) we just needed to make sure it worked as expected. Looking at the tests run on the original function, we make a promises version of the initial test.

it('should not unlink directories', function (done) {
   var fs = util.fs();
   fs.mkdir('/mydir', function (error) {
      if(error) throw error;
      fs.unlink('/mydir', function (error) {
         expect(error).to.exist;
         expect(error.code).to.equal('EPERM');
         fs.stat('/mydir', function (error, stats)  {
            expect(error).not.to.exist;
            expect(stats).to.exist;
            expect(stats.type).to.equal('DIRECTORY');
            done();
         });
      });
   });
});

With this initial test, we want to make sure the promises version works. Thus we convert the original to the promises.

describe('fsPromises.stat', function() {
beforeEach(util.setup);
afterEach(util.cleanup);
it('should not unlink directories (using promises)', () => {
   
   var fsPromises = util.fs().promises;
   
   return fsPromises.mkdir('/mydir')
          .then(() => {
              fsPromises.unlink('/mydir')
          .catch((error) => {
             expect(error).to.exist;
             expect(error.code).to.equal('EPERM');
   fsPromises.stat('/mydir')
             .then((error, stats) =>{
                expect(error).not.to.exist;
                expect(stats).to.exist;
                expect(stats.type).to.equal('DIRECTORY');
              });
            });
          })
          .catch((error) => {
             if (error) throw error;
          });
        });
      });

This conversion comes with understanding how it currently runs and how promises work. If you need help to understand the code, you should take a look at promises.

After we’ve got the test written, we run the tests again! We’re going under the assumption that the promises implementation is working properly.

Make sure you navigate to your filer repository. Those initial errors that were fixed were because I’m on windows

With everything passing, we’re good to go to the next step. We want to get this code merged with the code base.

The Pull Request

A pull request is essentially asking for your code to be accepted and merged into the master copy of the code base. In order to do so, we’re going to have to get our local copy saved into our branch.

I’m using the GitHub desktop application, so I don’t need to run the git add command unless I’m adding a new file to the repository.

The changes I want to commit are already staged since the desktop application realizes I made a change to the file, thus we need to commit it to our branch. This step requires you to have a summary and message for the commit. That way when people see your commit, they know what you’ve changed without having to take a look at the code.

Once that’s done, we go on filerjs repo on GitHub to create a pull request for our branch. We give the details of the change, what we’ve added and/or changed, why we did it, and link the issue associated with this change.

If you’re a master coder, everything should be good to go and your pull request is accepted and merged into the code base, woohoo! But thats not the case for a first-timer like me. Part of the process of contribution is reviewing Pull Requests.

Reviewing the Pull Request

Sadly, I created the pull request before having realized I made a dupe, so my pull request will probably be denied/removed later. But that aside, taking a look at my pull, you’ll see someones commented on my work! This is the best part of open source, everyone does their best to critique and give tips to write the most optimal code.

When this happens, you want to make sure that they’re right and if you agree, make your change and commit it again (If you do this through the desktop app, it’ll append the changes to the original pull request). The only review I got on the pull request was my spacing at the end of my commit. GitHub was flagging that it expected a newline, so no prob. Added the line and re-committed.

Otherwise, you can do the same. Go ahead and look through other pull requests and review (Don’t be like me and forget to SUBMIT the review when you’ve made it) what you think the coder should touch-up.

I noticed, looking through other pull requests, that this individual had went about using the promises variable differently.
I noticed he used var fs = util.fs(); thus having to use the variable like this fs.promises.function() member after the variable.
My suggested fix was just to instantiate the variable with a promise to avoid having to type promises over and over var fs = util.fs().promises; . Also, I got a bit cheeky and mentioned the newline issue I had as well.

Conclusion (Thoughts)

With my first pull request complete (although not accepted) I’m a little more confident with how I should go about contributing to open source. I’m slightly glad because now I know I need to be a little more thorough with investigating for issues and I’m a bit more aware of the coding styles and expectations (from looking at peoples pull requests/reviews).

Although I may not have been as involved with this community as I’d like, aside from the expected review, I did receive more help from the community. Not only did I read some helpful tips through our slack conversations, the gentleman who reviewed my code gave me a couple pointers as well.

In the end, everyone wants you to succeed, we’re all working together to improve the project, so take a step and give it a shot. You’ll only gain more experience with the different projects and everyone’s critiques and tips!