Contributing to an Open Source Project

Diving into a open source project can seem intimidating and daunting at first but when documentation is well written and you have google on your side it isn't anything impossible to figure out.

When I was testing this open source content management system called HAXcms I noticed a small issue that I thought should be fixed.

So after looking at their documentation on how to contribute and a couple of chats with the lead developer I had a development environment up and running. Now this did come with some hiccups that were related to my Operating System (fedora 31) which I am going to cover in the post.

First off HAXcms is built out of web components (reusable pieces of HTML, CSS, and Javascript). There were too main repositories I had to clone and fork. One was the HAXcms repository and the other one called the lrnwebcomponents repository, a repo that contained most elements in HAXcms. Forking a repository is essentially taking a copy of repo and saving it as a repository on your account. This is typically the first step when contributing to an open source project.

After I forked both the HAXcms repository and the lrnwebcomponents repositories I had to clone a local copy to my system.

$ git clone https://github.com/collinkleest/HAXcms

$ git clone https://github.com/collinkleest/lrnwebcomponents

There was also a couple of pieces of software I needed to get a proper development environment running. These were docker, yarn, docker-compose and ddev.
Here are the commands I used to install these on Fedora, these commands will vary depending on your system.
Docker Install:

$ sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

$ sudo dnf install docker-ce docker-ce-cli containerd.io

$ sudo usermod -aG docker $USER

Yarn Install:

$ sudo dnf -y install yarn

DDEV Install:

$ sudo curl -L https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh | bash

Docker-Compose Install:

sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Now installing all this software on your system may seem like a daunting task but if you can use google I believe anyone can figure it out. Also for all of these software their is documentation on and guides to installing on your system.

Once I installed all the necessary software for my system I had to get the development environment setup so I could work on the feature I wanted to add. With following documentation and recommendations from the lead developer I installed the node dependencies inside the lrnwebcomponents repository and made a symbolic link on these node modules to the haxcms folder so it can utilize the node dependencies without installing them in the hax directory.
Here are the commands I executed to do this.

# change directory into the lrnwebcomponents folder
$ cd lrnwebcomponents/

# install the node dependencies with "yarn install"
$ yarn install

# change into the HAXcms directory
$ cd ../HAXcms
$ sudo ln -s ../lrnwebcomponents/node_modules

After this I was almost sure that everything was perfectly setup to begin development, I was wrong. When running ddev start in the HAXcms directory to get the content management system running I ran into a issue. This issue seems to occur with the newer versions of Fedora particularly Fedora 31 and 32.
This was the error I was getting cgroups: cgroup mountpoint does not exist: unknown. I initially had no clue what was causing this but after a bit of research on google I found that the newer versions of fedora use cgroupsv2 when Docker only supports cgroupsv1. I finally found a "unthethored" temporary solution to this issue on the docker issues tab on github. The solution follows:

$ sudo mkdir /sys/fs/cgroup/systemd
$ sudo mount -t cgroup -o none,name=systemd cgroup /sys/fs/cgroup/systemd

Now I was ready to begin development, the feature I wanted to implement was a simple url redirect to the sites page in haxcms.
This is what the element looks like.

All I want this button to do is redirect me to the sites page of HAXcms where I can manage all my sites, it's almost like a dashboard or a "go to home" button.
This is how I implemented it, I had to add an onlick event handler inside the element itself. After looking at the LitElement Documentation I found an example of how I can call a function when the element is clicked.

<paper-avatar
        @click=${this.redirectToSites}
        id="username"
        label="${this.userName}"
        two-chars
        src="${this.userPicture}"
></paper-avatar>

Then I had to write the actual function that redirects the user back to the sites page. After some research and google searchs I found out I could create a temporary anchor element, and grab the url from the anchor element with anchorElement.href. I also learned some JavaScript Regex from freecodecamps web development course. This allowed me to extract if the http method is standard encrypted http or encrypted https.
In the end this is what the JavaScript function looks like.

redirectToSites() {
    let redirectUrl = "";
    let webTypeRegex = /^http/;
    let tmp = document.createElement("a");
    tmp.href = window.location.href;
    if (webTypeRegex.test(tmp.href)) {
      redirectUrl = `http://${tmp.host}`;
    } else {
      redirectUrl = `https://${tmp.host}`;
    }
    window.location.replace(redirectUrl);
  }

Result

Conclusion
Contributing to an open source project is something every developer should do. Not only is it a good learning experience but you also get the good feeling of helping others with a project that is for the greater good.