Sunday, October 27, 2019

Plexis - An open source community project

Plexis and toSwap - Not Just a Function

So it's been a while... I didn't want to leave this for so long, but school got the better of me, and I fell behind. I've just come off a very restless study week, and now it's time for my third pull request of Hacktoberfest! It took me literally 2 days to find the issue I worked on, and my fourth and final issue is still in the works. But, as usual, I am getting ahead of myself...

Plexis is a string manipulation library, that is purely community driven. This is one of the main factors that drew me to plexis. I wanted to get involved with a community and I think plexis is something that I will work on again, and possibly join the community. The focus of plexis is to help newcomers to javascript get used to open source project development and maintenance. It is also in the form of a library, meaning that my function will be part of an npm library. I was so excited to get started!

Choosing the Issue

The issue I chose was to create a swapping function, called toSwap. toSwap accepts a string as input, and swaps each set of 2 letters in a string, until reaching the end of the string. For example:

toSwap('ab'); //returns 'ba'
toSwap('hello world!'); //returns 'ehll oowlr!d'

This function is by no means difficult to write, or challenging to implement, but the challenge turned out to be in testing and formatting. I chose this issue for the community aspect, which I will get into more later, and the fact that I've never worked on a library before, and I was interested in the pitfalls I might encounter.

Preparation to Create the toSwap function

First, I had to fork and clone the repo, a process I have mastered compared to my first pull request back in early September. I had to install yarn and lerna in order to get started, and learn-a how to use them (sorry for the bad pun but I had to!) Yarn is similar to npm, as it manages node_modules packages, and was fairly simple to understand and get familiar with. I have never encountered lerna before, and on researching it, I discovered that it is a tool used to manage javascript projects with many packages. In order to create a new package in plexis, I had to install lerna globally, and learned how to use it for the purposes of this project (I won't make the pun again).

The project also made use of npm in conjunction with yarn, and jest. Npm is a very common package manager, and Jest is a testing framework that is also being run by yarn.

The Solution and Pull Request

Creating the Package

I ran the command "lerna create @plexis/to-swap" to create a package named to-swap. This package had to be renamed and changed to follow the template required by the repository owner. There are four important parts to each package: src, test, package.json, and README.MD. 

Src

This is where the source code is stored for the function itself. Included within was simply the toSwap function, implemented by splitting the given string into an array, iterating through the array and swapping the necessary values, and then joining the array back into a string. A simple function, and the easiest part of this whole process. I have also included jsDoc information for the function at the top, denoting parameters, returns, and examples.


test

Test contains a file that stores all of the Jest test cases. These test cases are simply there to test my function, and see if anything breaks it in the future. I have test cases for small strings, longer strings, odd numbered strings, and empty strings. I also included cases with spaces and non-alpha-numeric characters.


package.json

I am not going to show the package.json file as it is boring, and very little is to be gained by looking at its code. Essentially, lerna uses a package.json file in every package in the plexis library. These package.json files are linked together in a lerna.json file. This makes additions to the library really easy to do and reduces the amount of work a maintainer has to do. The file contains the name, description, version, and locations of the source files for the plexis library.

README.MD

This is simply a description of what the toSwap function does, with examples and aliases. It is written in markdown and is commonly found on Github, but you know this...

Pull Request Status

I have submitted a working pull request that has passed all tests, and I am waiting for approval. 

Interaction with the Plexis Community

So far, I have only interacted with vorillaz, who looks to be the most active member and possibly the owner. He has been very pleasant and welcoming. We have had many conversations and I have asked for his help with multiple aspects of this project. Although it seems simple, and the code is VERY simple, actually getting it to submit and pass all tests was difficult. He helped me to understand all of the extensions that were being used, and I think that I learned a lot from him.

UPDATE OCT 28: I also interacted with Brandon Skinner, who informed me that I was missing the API documentation. I quickly added it and now I am waiting for approval again.

In the future, I plan to continue to interact with and contribute to this community, especially now that I know how to add packages and I am very familiar with the process. I think that their focus on community is strong, but still small. I don't think they even have a slack, or any means of communication aside from Github. 

Problems I Encountered

This project was a rollercoaster. I had so much to learn and adapt to and was equally infuriating and enlightening. Some of the problems I encountered and the things I learn-a-ed (I couldn't resist!).
  • Finding the issue itself (took 2 days)
  • How to install and use lerna (finding documentation was very difficult for some reason)
  • Creating the package template (dead links lead me to 404 pages, had to ask for help)
  • Asking for help (something I struggle with daily)
  • I created all the tests and added everything, and nothing worked
    • I couldn't figure out why, so I created a pull request anyway and researched
    • I ended up figuring out that I had missed a file, and created it.
    • It is essentially the same as the source file, and isn't even included in the repo.
    • For some reason, it works now, and has passed all tests.
    • Hopefully, that's it for now.
I am hopeful to complete my Hacktoberfest with a bang, as I look for my last issue with only 4 days left.


No comments:

Post a Comment