Wednesday, December 4, 2019

Release 0.4 - OpenClimateFix and the Github API

And so it ends...

As my course winds to a close and I finish up my assignments, I have reflected on everything I've accomplished in the last three months. I'm proud of what I've done. I've made 6 pull requests in public repos, 4 of which were merged, 1 of which is dead, and 1 is yet to be merged. I've looked at hundreds of issues in dozens of languages, learned so many things it's taken me 15 or 16 blog posts to contain them all. I am most proud of my work in this pull request, although on the surface it looks rather simple.

The Issue

The issue is built upon my previous pull request for Release 0.3, which is why I thought it would be perfect for 0.4. It is a new page on the website that includes the Contributor Showcase component I built for Release 0.3, as well as a paragraph on how to get involved, a couple of links, and a link to a github search for issues. It also includes a list of the repositories owned by OpenClimateFix. Another part of this issue is to attempt to add the Github API to the Get Involved page, to load the issues instead of clicking on the link. This is what I spent approximately 20-30 hours researching, learning, and testing before I found that I could not do it in this pull request. I figure what better way to use that knowledge than to impart it on the readers of this blog.

Why I couldn't use Github API

In order to use Github API, you can do 3 things:
  1. You can use a personal access token, which provides access to the Github API through your Github account. 
  2. You can set up a Github App, which means setting up a server to host a Github App to fetch data from the API.
  3. You can authenticate using a OAuth app in a similar manner.
What you can't do is use a personal access token on a public website. Everywhere I researched said explicitly that the point of the access token is for testing and maintaining your own repositories, and it is meant to be temporary as it only lasts for a year. It also can be used instead of a github password, which would give others access to my account and private repositories. The other 2 options would have to be done by OpenClimateFix, and would be a project on their own to get set up. The simplest solution is to just make a good Github search query link, and provide links to some of the repositories staticly.

Setting up the environment

Luckily, I have done a few PR's for OCF now, so I have the environment set up. I looked at many new packages and libraries to use the Github API, but in the end I had nothing to add. For your sake (the readers of this blog), I will include what I needed to get the Github API running. If I was making my own app, I would probably fetch the data differently, and not use Gatsby, but this is what I got working with the personal access token:
Then all I had to do was add the Github API query to my code, similarly to how I used a query in Release 0.3. The following code shows the query: 

query MyQuery {
  github {
    repository(name: "repository-name", owner: "owner") {
      id
      description
      issues(labels: "good first issue", states: OPEN, first: 10) {
        edges {
          node {
            id
            title
            url
          }
        }
      }
    }
  }
}

When I realized that personal access token was not going to be an option, I had to go with the backup plan.

The Solution (Pull Request)

The backup plan was to include a link using a Github search url to define open, good first issues available from all openclimatefix repositories. Here are the steps I went through to create the new page.
  1. Create a file named get-involved.jsx under the pages folder. This automatically creates a page in Gatsby, and routes it to the root uri followed by the filename. If the file was in a folder, it would default to `root/folder/jsx-file`. Classes are also added to the routes, so if I wanted to put all of my classes into one file I could, and have several routes. 
  2. Write the code to create and return the Gatsby html template.
  3. Add the existing code from the Get Involved section on the website. This includes the Contributor Showcase component I created for Release 0.3, as well as some links, and I added the new link for good first issues. I also left OCF some room to write their own message on the page.
  4. Format everything to fit prettier and eslint standards. The repository does not run eslint tests on compilation or on commit, but only in the pull request itself. Therefor, any errors are difficult to catch until you have made a pull request. It took several tries to fix the lint errors.
  5. Wait for a Review. I am currently in this stage, and will post an update if I hear anything back from OCF.
The Final Product

Overall it was a fairly simple solution that I spent so many hours researching for. I'm glad that through this blog post, my research and experience might help someone else get the Github API going in Gatsby. I found no guide suggesting where to go and what to do explicitly, so let this be a sort of guide. 

My Final Thoughts

As this course ends, I find myself disappointed and proud of myself. I am disappointed that I did not end up working on an issue for a larger company, like Microsoft, Google, or Amazon. I imagined my code up on some Google application, or as an addition to the newest stable build of Visual Studio Code. I would have liked to see a bug fix of mine in GIMP. But I ended up working on some amazing small projects, and that is what I am most proud of in this course. I found so many awesome projects, some of which I couldn't really help with and others I got heavily involved in. I am glad that I kept this blog (even though it is mandatory) because I know that I'll continue it, and maybe even take it with me to my next professional option course (on android app development). This will be my last blog post till after Christmas, so Happy Holidays to anyone reading!

Release 0.4 - Telescope's Documentation Problem

Why Documentation is Important

I have been working all weekend to digest the entirety of the Telescope repository for my course. I have been mentioning it for weeks now, but I'd like to go into detail now that I know more about it. Telescope essentially grabs blog posts from a feed centralized on a Seneca College website, and displays them on a front end app. This project has been moving very quickly, it only started a month ago and we are days away from a working prototype. But as quickly as it has been moving, the documentation has not been maintained at all, something I foresaw weeks ago when I made the CONTRIBUTING.md file for the project. I intended as developers added their code they would update the documentation, but they have not. 

When setting up the environment this weekend, I had great difficulty in understanding how and why things needed to be done. This is the point of documentation, to assist people in downloading and running the environment required to start development quickly. I am devoting my time on Telescope to solving these documentation issues, not just for the current developers but future developers as well. Now to the issue.

The Issue

Basically what needed to be done was to add documentation on docker, which has become a major component of the project, and how to set the .env variables. I have to talk to several people over the next few days in order to get this information, a process I have already started. Most of the information is readily available through the commit history of the env.example file. 

Background Information and Documentation

The following paragraphs detail what I learned in finding every avenue to install docker, and get the system running in different environments:

Virtualization

I had to learn how to properly set up a virtual machine. Mainly this was to get telescope running on a system that I could use. The main issue was that docker is not readily available on Windows Home Edition. At least so I thought at first. To even run docker, you need to have a virtualization capable system, and in some cases have to enable it in the BIOS. I decided to leave this out of my documentation as it is out of the scope of the project, and there are many guides online that can help you with this process. I even linked to a few guides and youtube videos in the documentation for assistance with certain steps.

Docker

I had to learn how Docker installation works, it's requirements, and what systems it can run on. This included finding alternatives for people who did not have access to the easier methods. For example, getting Docker for macOS is as simple as downloading Docker for Desktop. It will set up docker for you and comes with docker-compose pre-installed. On the other hand, Windows 10 Pro, Education, or Enterprise are required for Docker for Desktop to work. You need to either set up a virtual machine with Ubuntu Linux, get Windows Education Edition (an option freely available from Seneca), or get Docker Toolbox, which is an older version of Docker Desktop with less features.

On top of that, I had to learn how Docker works. It didn't occur to me that Docker essentially builds a miniature virtual machine to run build instructions in a consistent environment across devices, similar to my understanding of Java and it's environment. The difference is that Docker is fully customizable, and can use Docker images to use software that you would normally have to install natively, in our case this is Redis.

Docker-Compose

Docker-compose allows you to run docker applications by starting all services with one command. It is a separate install from docker on Linux distributions, and comes with Docker for Desktop on Windows and macOS. It is vital to the project as docker-compose is required to get the docker image of Redis running as a service on the right port. 

Chocolatey

Chocolatey is a package manager that was recommended to me by my professor as an easy way to download Redis natively. Part of my job was to investigate not using docker, and I found that although you can run the website locally without any major issues, it takes a lot of configuration and extra work rather than using docker. My recommendation was to entirely remove the native set up instructions and stick to docker.

The Review Process (Pull Request)

The review process took a lot longer than I initially anticipated. It took approximately 4 days to go from pull request to merge, and there were a lot of changes along the way. I came into the process with a limited understanding of exactly how everything fit together, and I have walked out knowing exactly how it all works. I was reviewed by Manekenpix and Silvyre, who are both extremely active in the project and have done many pull requests. Some of the concerns raise were as follows:
  • Code Syntax
  • Wording Problems
  • Grammar
  • Usage of sudo (when and why)
In total, between the three of us we made 35 comments, each of which added to the discussion of how much to include, and what should be excluded. This shows it's importance, as even extremely active community members take an interest in proper documentation.

I learned many things during the review process, including:
  • Docker Toolbox (Thanks to grommers00 on Github)
  • Docker for Desktop on Windows Education Edition (Thanks to MeisterRed on Github)
  • The proper usage of sudo
  • How to properly set up docker on Linux (with post install commands)

Overall Feelings on the Project

I feel like I made a good contribution to the project. Although I didn't contribute to the code itself, I can take solace knowing that future developers that work on the project in it's next iteration will be able to adapt and understand the code faster than I could. I have already had some people thank me for my contribution, saying it helped them get their environment set up better than they had it. I have enjoyed my time in this course, and this was a nice cherry on top. But there is still one more blog post to do after this one, and it contains my proudest moment in this course.

Thursday, November 28, 2019

Release 0.4 - Docker and The Search for An Issue

Progress So Far (Nov 28)

Telescope - I have 2 issues I am currently working on.
External PR - Still looking for an issue, but I have a potential one lined up.
Release 0.3 - Pull Request is still open, working on getting it closed.

Telescope

Getting Telescope Set Up

Until I discovered Windows Subsystem for Linux, I used a virtual machine for web development. I hated it. I hate virtual machines, at least my virtual machine. I have an excellent gaming PC at home that is one of the fastest I have ever used, for coding or otherwise. And instead of using it, I have to use a stupid slow virtual machine. WSL was amazing. I got the combined speed of my PC and the accessibility of linux commands and libraries. That is until telescope. 

Telescope requires docker, which cannot be run in WSL or on my Windows 10 Home Edition. It must be run in Ubuntu proper, MacOS, or Windows Professional. So I had to break out my stupid dumb annoying virtual machine and figure out installation. 

I was able to get the front end part running on my PC, as well as all the tests, so I am currently looking for more front-end related issues to work on. I am also working on a documentation fix and I have asked to look into a simple file name change as well. Of course, every reference to those files must also be changed, and tested.

External PR

Potential PR (if I get a response)

My potential external PR is to make the Get Involved page on the openclimatefix website. It involves possibly working with the Github API, page creation and routing in Gatsby. This seems like it would be a good PR, the only issue is that I am unsure of the activity of the project. I really like working on openclimatefix, because it's mission is something I agree with and the Github community has been very helpful to me. What started out as an emergency pull request at the end of Release 0.2 has become a project I genuinely care about. But if I hear nothing back from them I have to find something else.

Release 0.3

I have contacted Flo, the main contributor I have interacted with on the repository, to see if my solution can be merged. If not, I will work until it is. It seems like Flo is a bit distracted, and not really working on the website, so for now I will just have to wait for a response. 

Thursday, November 21, 2019

Release 0.4 - More Github, More Problems

And so it continues....

After the spectacular disaster that was Release 0.3, I have returned this week for my fourth and final release. At this point, I am happy with everything I have done so far in this course, and these last few weeks will test everything I have learned so far. To start, I am going to go over some updates from last week's posts, and explain my plans for Release 0.4.

Release 0.3 Updates

I received some change requests from Flo as follows:
  • Make different grid sizes for different screen sizes
  • Try to use tailwind classes to attempt this
  • Change some syntax and naming
  • Adjust font size and justification
The conversation is listed here. So I successfully made these changes to the code aside from using tailwind. I couldn't get tailwind to work with the .module.css file type, as tailwind works better with regular css. I used some of the syntax to adjust font size and justification, but I couldn't the other way. I ended up using the @media method to detect screen size and adjust the grid to the required size. Some of the changes made also help with a compression issue, where some images were being squeezed to fit in the grid at certain screen sizes.

@media method

300px is for phone screens, 768px is for tablets, 992px is for smaller computer screens, and 1200px is for larger screens. Each of these has a different number of columns to fit the screen. 

Telescope - Release 0.4

I have picked an issue to work on for Release 0.4, to continue my work from 0.3 on documentation. My plan is to work on this issue to start, and then continue to monitor and update documentation as the Release continues. Part of my problem is that I have no way as far as I know to install docker in my current environment. I use WSL (Windows Subsystem for Linux), which cannot use docker, and I need Windows Professional to use docker desktop. I am stuck working on documentation and organization until I can get docker up and running. I am going to continue researching ways to get docker going over the weekend.

External PR - Release 0.4

I really enjoyed working on open climate fix this week, it made last week's madness feel a lot more legitimate. In terms of an external PR for Release 0.4, I really want to work on a page for a website. I would love to continue working on open climate fix, however there doesn't seem to be an escalated issue on that site at the moment, except for a contributing page which I am unsure of the complexity of. I am currently searching for an issue similar to what I have worked on these past 3 months. My criteria for a new issue are the following:
  • UI related (components, new pages, new features)
  • In an environment I am somewhat familiar with (Gatsby, React, Angular, Javascript, etc)
  • An escalation from my previous issue (a gatsby component with simple file reading)
Some issues that I have found that somewhat satisfy my criteria:

Friday, November 15, 2019

Release 0.3 - Third time's the charm?

OpenClimateFix - A New Issue

Here we are again. I have bounced from issue to issue, hitting roadblocks as I go. I know that the issue I have picked here is not as complex as tania-core, but I believe it is a little more complex than WritingSwarm and is in a system I am familiar with. I am devoting all of my available time to completing this issue, and I intend to have a pull request up by tomorrow night. In order to do that, I will have to work hard in order to get this done, and I am committed to doing that.

The Issue

The issue I have chosen is to create a contributors showcase component, for a new Get Involved page on the openclimatefix website. I have worked on openclimatefix before, as my last pull request for Release 0.2. In order to populate the contributors showcase, I must read a json file containing each contributor and display their name, profile url and github avatar.

Setting up the Environment

I already had the environment set up as I have worked on this project before. It uses yarn to install dependencies, Gatsby as a framework for development, and a host of dependencies to run tests and ensure consistent formatting. I updated my fork of the repo and created a new branch to work in. 

In terms of research, although I have used Gatsby before, I have never created a new component. I had to figure out the conventions used in the openclimatefix site and copy those conventions. I also had to figure out how to read a static json file in Gatsby. Turns out you need an extra plugin, called gatsby-transformer-json in order to read in json files using graphql. graphql comes with Gatsby and is used to manage static and dynamic data in a website. I also had to learn what a StaticQuery is in Gatsby, in order to display the results of the graphql query. 

The Solution and Pull Request

The Component Code

Component Display Code
This function returns the Contributors header with each contributor displayed below it. The StaticQuery has 2 properties; query and render. query uses graphql to query the json file named contributors.json and get the contributors attribute's contents, in order to create a javascript object containing each contributor's name, profile (url), and avatar (image url). The render property will run a function to render the data generated using the function getContributors().

getContributors()

getContributors() receives the object generated by the graphql query
getContributors() receives the data from the json file and for each contributor makes a <div> element to contain the contributors profile image, and their name, which is also a link to their profile. In order for the render to work, a key must be chosen, so I used the name property for this key. For each contributor in the contributors array, a div with their information will be appended to the cont array, and return to the component code. This will populate that code with each grid item, ready to be displayed.

CSS

Basic CSS to set up the grid

Css works a little differently in Gatsby than it does in regular HTML5 development. It is called like an object, with each class represented and called to as an attribute of that object. Whenever you see "styles.something" in the className properties above, they link to a class in the CSS document.

Final Result


Interactions with Flo (FWirtz)

Flo is the maintainer of the repository, and is very helpful and communicative. She and I have not talked much during this process, but she did assign me to the issue. We have talked before on my previous 2 issues in openclimatefix,  and I expect to hear from her about this pull request, although I don't think she has reviewed it yet.

Release 0.3 - Overall Experience

I felt very rushed in this release. We only had 2 weeks really, considering Release 0.2 was due Oct. 31st and I needed to work on it until then. I had other commitments, and as hectic as October was, November has been worse so far. There are only about 4 weeks left in the semester, and in that time I have to complete Release 0.4. Although Release 0.3 was difficult for me, and I'm not sure how well it went, I know that I'm much wiser and more aware of my abilities. For one thing, I am going to avoid databases for Release 0.3. Secondly, I am going to find a good issue early on, and get started on it right away. 

Thursday, November 14, 2019

Release 0.3 - Failure, Again...

The old song and dance...

So we've come to another deadline, and again I am running late. I had an issue to work on, with tania-core and it's SQL to CSV conversion. Turns out this was a much larger undertaking than I expected. I might still work on it for Release 0.4, but I'm unsure if I have the knowledge in SQL and Vue to even attempt tania-box. I worked on it this weekend but with little success, and with time running out and pressures from other courses, I had to find another issue quick. To my surprise, I rediscovered an issue I had commented on but had never been assigned to and jumped on it. I am working on WritingSwarm now, which has already been an interesting project and has opened my mind to a completely different world.

WritingSwarm and the Issue

WritingSwarm is a Dapp for writing short stories collaboratively using the Etheresphere Swarm backend. Sounds complicated, and it is, but first what is a Dapp. A Dapp is a distributed app, meaning that it is run on a distributed system. A distributed system is a a network of computers that pass information between them to achieve a common goal. Swarm is a peer-to-peer distributed storage platform and content distribution service. WritingSwarm uses swarm to develop and share short stories. 

The issue involves adding an auto-save feature to the WritingSwarm site, which is built in Angular. I have used Angular before but never Swarm, so it has been an interesting experience to say the least. Basically, the site already has a save feature, but the user is required to press a save button in order to save their work. My task is to add a toggle switch that toggles between "ON" and "OFF" states for the WritingSwarm environment, and in order to do that I need to use Angular Material, which I have not used before.

The Environment

The hardest part of this issue is getting Swarm up and running, because connecting to it is not simple. In order to develop this project, I have to set up a Swarm node, learn Angular Material, and adapt the existing code to provide the auto-save feature. 

In order to get swarm, I had to use go, which I was fortunate enough to have installed when I was trying to get tania-core up and running. I also had to get geth, which stands for go-ethereum, the official go implementation of Ethereum. Ethereum is basically an open source platform for Dapps. So in order to run WritingSwarm, I had to get an account in Ethereum for go, and download swarm to set up my node. Once I logged in, my node was set up and I was able to serve WritingSwarm on my localhost.

So it started running, however when I try to add a file, I keep getting an error message. I sent a message to Kortatu, the owner of the repository and I am waiting to hear back.

UPDATE: Nov 14

I have not heard back from Kortatu, and the more I hear about Swarm the more I dislike using it. I don't really trust it, and was only using it because I was running out of time. Well now I'm stuck and out of time, so my only option is to find something else. It is very late and I don't expect to do well on this, but I need something to hand in on Friday. I have found a new issue on an old project and will be detailing it in another blog post. I hope to have something working by Friday, and for Release 0.4 I will be more proactive on my external pull request, like I was on my internal one.

Thursday, November 7, 2019

Release 0.3 - A new experience altogether

Release 0.3 - Telescope and Tania-Box

What is Release 0.3

As my open source course moves on from Hacktoberfest, we have switched to working internally and externally on open source projects. For release 0.3 I had to work on telescope, a new app for tracking the blog posts of all the students in my course, and I had to find another issue to work on and submit a pull request. I have had a lot of success in one of these, and little in the other. I will provide an update next week on how things have progressed.

Telescope

I have made a lot of progress in Telescope. I have already had my issue read, created my solution, and had my pull request merged after a review by two of my peers. Let's start with the issue.

The Issue

My issue was to create a CONTRIBUTING.md to create a centralized place for environment setup instructions, prerequisites, and testing information. It would also include a list of the technologies we are using, as well as provide a guide on making issues and pull requests. Finally, it would display the MVP features, features we need to create the most basic version of the website.

Research

I looked at many different CONTRIBUTING docs across many projects in order to get an idea of what I wanted to put in there. I also needed to research Redis, as at the time it had just been added as a requirement to the project and the instructions for set up were non-existent. I researched for a few hours and got all the information I needed. Redis is an open source noSQL database. It is used by our app to create a queue to load blog posts from the list of feeds in the feeds.txt file.

The Solution and Pull Request

I created the CONTRIBUTING.md document, which I will link to here. This document contains information on creating issues, and creating pull requests, based on course requirements during Hacktoberfest. It also provides links to the prerequisites for cloning and running the code. These prerequisites are Node.js and Redis. Instructions are also provided for installing Redis on Linux and on WSL (Windows Subsystem for Linux). I did not include the Windows or MacOS set up instructions, as I cannot test either. I do not use Windows for my app development environment, I use WSL. I do not own a Mac, nor do I have the means to get a virtual machine version. I left those to others who need issues to work on. 

I also included a checklist version of the MVP Features list, to provide a way of checking whether or not we have completed any or all of the goals laid out there. Finally, I included the setup instructions to get the code running. 

Setup Instructions

You need to run "npm install" to install dependencies, and "npm start" to start running the code. If you get error messages, you may have to run "redis-server" in a separate window in order to start the server, and then try again.

So now what?

Well, Release 0.3 is part internal and part external. Although the mandatory internal part is technically done, I still have to work on an external issue. And the one I've found looks quite difficult. 

Tania-Box

I actually asked and was assigned to this issue about 2 weeks ago. It is more complex than any issue I have faced so far, and I am even considering moving this issue to Release 0.4. It depends on how complex it is going to get. Right now, I have set up the environment on my home PC, and I am starting to understand how it works. Progress is not great, as I have too much in other courses going on this week. I am hopeful that I'll have time this weekend to work on it.

The Issue

The issue is to create a new menu for converting the SQL database to a CSV file. I am unfamiliar with the database, and how I would even go about doing this. I am going to attempt it this weekend, and if I cannot, I will find something else to do.

Background Research

I have done some research on it, as it uses Go primarily, a language I am fairly unfamiliar with. It also uses SQLite, which is a database engine, and working with databases was one of my goals from Hacktoberfest.

Wednesday, October 30, 2019

Hacktoberfest - 4 Pull Requests in 4 weeks

Hacktoberfest: Status as of Oct 31st

I started off strong with pacdiv and the regex.guide app, which I'm proud to say still includes my reset button. I plan to contribute more to pacdiv's app in the future as I really enjoyed the experience and I liked using Gatsby.

Emojipages continues to expand, however it seems like my pull request was left in the dust. It is well behind the current version. I thought the repo owner Brittany was taking her time to read and review the code, but it turns out she just ignored it completely. I plan to update it to the current version, and try to resubmit, but I'm afraid that I just don't have time to do it before Oct. 31st. So I plan to work on it in my own time next month, or possibly for Release 0.3.

PlexisJs has updated and not included my code, I am updating my pull request as I type this in the hopes that it is accepted soon. It may be too late for Hacktoberfest, but I really want this to go through as I really liked the community.

On a brighter note, my last pull request to OpenClimateFix was reviewed and merged by the maintainer FWirtz.

My Experience

This month was like a roller-coaster, and one of the most difficult I have ever had in school. I had a LOT to do this month, and Hacktoberfest was by far the nicest part of the month for me. I had a lot of assignments, midterms, tests, and pull requests to make this month, and I barely got it all done. My study week was spent researching, writing, and fixing code, and virtually nothing else. It was a terribly difficult month for me. The silver lining was Hacktoberfest in the end.

I got to see all of the amazing projects my peers worked on, and I even got to work on some of those projects myself. I searched through hundreds of interesting projects and communities, and found many projects I wanted to be a part of, but was too inexperienced in the material or lacked the time to get involved in. The projects that I ended up working on were all great projects with amazing goals like researching climate change using open source technology, teaching Javascript programming through a library that anyone has access to, and making regular expressions easier to make and more accessible to new programmers. I also participated in making a game, something I've always wanted to do, and even though it was a simple quiz game I learned a lot about Javascript while working on it.

Goals

I set four goals at the beginning of Hacktoberfest, two of which I now realize were a little too ambitious for different reasons, and two of which I achieved multiple times this month. The goals are:
  1. To work on a product that I use frequently, and have my pull request confirmed and accepted to the project.
  2. To learn more about databases in a project that I work on, as I am very interested in database design.
  3. To contribute to a project that involves UI design, which I love to work on.
  4. To ask for help from my community and the online community as well.
For my first goal, I failed because it turns out that the projects I had in mind (GIMP, Musescore, and StarUML) were all either not on Github anymore, never have been, or are almost dead entirely. I looked for others but it turns out I don't use that many open source programs, and I couldn't find issues in other projects that I had any notion of how to find or fix.

I failed my second goal because it was extremely difficult to find any projects that used databases on Github, in any language that I knew. I eventually found one but it was too large for me to finish this month, and is one of the possible issues I might work on for Release 0.3.

My last 2 goals I succeeded in many times. Almost all of my projects involved UI design, and it solidified my resolve to become a web developer, as I was unsure before of what field I was most interested in. The last one of my goals turned out to be the most important one of all, the thing I needed to learn most was to ask for help more often. Every time I asked for help, my big issues became small quirks that fixed themselves. I was nervous at first to ask for help, preferring to do things my own way, and now I am more eager to ask for help than ever before.

Monday, October 28, 2019

OpenClimateFix and OpenGraph

OpenClimateFix, OpenGraph, and the Issue That Saved Me

I have had an interesting time this month. I will detail my experiences with Hacktoberfest in a later blog post, but yet again, I've gotten ahead of myself. You know the drill...

OpenClimateFix is a non-profit research organization using open source to spearhead projects to help the environment. Their website displays their initiatives, goals, and sponsors, and it is imperative that they be shareable on social media. Which is why they need better OpenGraph representation.

Choosing the Issue

The issue I chose was to adjust the OpenGraph representation of the site. In order to do this, I had to research a few things. First of all, what is OpenGraph? OpenGraph is protocol for creating meta information on websites, in order to create previews of those sites when sharing the link. For example, if I were to share a youtube video, a preview of the video will load and a title, description, etc.
Example: Youtube Video
The issue was to add an image to the OpenGraph metadata, for both twitter and other sites. A sample of the old version is shown below:
Old OpenGraph Link
 Preparation to Update the OpenGraph Metadata

The project is compiled with yarn and run with Gatsby surprisingly. Gatsby was the bane of my first pull request, as I learned to use it. So at least I know that. The other thing that I had to learn was how meta data is generated and used, which I have not used before. I have worked on web development courses before, and yet I have never created metadata. Finally, I had to understand the OpenGraph protocol, which was surprisingly easy to learn. It is simple, and easy to grasp, I just had to read their website which I linked above.

The Solution and Pull Request

Simplest Solution of the Month

I had to compile and run the project in Gatsby in order to test my code. I edited one file: seo.jsx. This file contained the code to create all the meta information, and I had to add 2 new meta elements. Both of these elements look similar, and for both the image links to the github url of the website logo, as the image property cannot point to a file. The image must be available online.

Adds OpenGraph image link
{
property: 'og:image',
content: 'https://raw.githubusercontent.com/openclimatefix/website/master/src/
images/logo_dark_square%402x.png',
},

Adds OpenGraph twitter image link
{
property: 'twitter:image',
content: 'https://raw.githubusercontent.com/openclimatefix/website/master/src/
images/logo_dark_square%402x.png',
},

The new OpenGraph Link

Testing

In order to test my work, I couldn't simply copy the localhost link into twitter and see the OpenGraph representation. So instead, I got a chrome extension called Localhost Open Graph Checker that retrieved my metadata and created a URL for me to test my OpenGraph metadata on, which worked.

Pull Request Status

I have submitted a working pull request, to my knowledge.

Interaction with OpenClimateFix

To be honest, there has been no communication with them so far. I am confident I will receive a reply to my work eventually, but for now I have heard nothing. Other students in the class have worked on this project and have talked to the owner, in fact I found this project by reading blog posts. I have interacted more with my classmates that OpenClimateFix.

UPDATE OCT 30: I have received a message from the repository owner that they will review and merge my request before Hacktoberfest. I will provide an update tomorrow.

Aside from this, I also tried to contribute to one of the other issues on the site, a much more complicated issue involving moving an image of clouds in the background as you scroll on mobile. It would have been a bug fix, something I've been wanting to try for a while. The problem is that this issue is impossible to fix with the current architecture or requirements. The site uses jQuery to update the cloud image on desktop, but jQuery itself does not track scrolling on mobile. In fact, because iPhones freeze the DOM while you drag across the page, you cannot update the clouds as you scroll. The only solution is to animate the clouds to move, and that would require an new issue. I reported this to OpenClimateFix devs, and I am waiting for a reply.

UPDATE OCT 30: FWirtz responded and thanked me for researching the issue.

Problems I Encountered

This project was simple but interesting, and I didn't encounter too many problems, however:
  • I had issues with the first issue I picked, as described above.
  • I have had little to no contact with OpenClimateFix community
  • I am unsure if the change is good or not, as I await some kind of response.
At least my Hacktoberfest experience is over, and although it has been fun, my next blog will detail what I learned and how my perspective has changed over the course of the month.

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.


Monday, October 14, 2019

EmojiPages - The Challenges of User Interfaces

EmojiPages - A study in CSS and Javascript

EmojiPages is a website, created by brittanyrw that is essentially a game. It has a listing of books and plays represented by emojis that react when clicked to display the actual title. The main problem with the game is that the user has to play it themselves. They have to have the patience to guess what the emojis represent and handle the revealing moment that shows what it actually represents. My issue was to take care of this process for the user, by introducing a quiz game mode.

Choosing the Issue

This issue challenges me in 2 ways. Firstly, I have never created a basic javascript + html site before. I have no idea what the pitfalls and challenges will be. I have never created a reactive web page without using a framework or bootstrap. I will also need to use jQuery, which I have little to no experience with. Secondly, I have the opportunity to create my own UI, without guidelines except for functionality. The only requirements I have are the following:

  • A button or link from the homepage to the page where the game is.
  • A button or link back to the homepage from the page where the game is.
  • The user should be guessing the song name.
  • On game start, randomly sort the cards and display them to the user. Up to you if you will display one at at time or all at once. The user should type their guess into an input box. Up to you if it will check their guess after they click away from the input or they have to press a submit button.
  • At the end of the game, show the user their score.

Preparation to Create the Quiz Mode

First, I needed to understand the kind of website I was working with. When I learned the site was essentially built from javascript and html files, I thought that this issue would be easy. However, what I would soon realize is that the project uses jQuery, something that I became familiar with as I worked. I also had to learn how the app populates the card display, as it is done programmatically through jQuery, and is a very complex html hierarchy.

The environment on the other hand was very simple to set up. All I had to do was clone my fork and use visual studio as my text editor. I would keep the html pages up in my browser to monitor the UI side of things.

The Solution and Pull Request

My Setup

I added a quiz.js file to handle quiz logic and jQuery functions, a quiz.html to display the new quiz page, and I added to the main.css file with the css styling for my buttons and UI. Aside from that, I made alterations to the index.html file, which handles the main page of the app, to add a navbar to navigate between the 2 pages.

Navigation

In the quiz.html and index.html, I added the code pictured below to add a navbar into the app. This navbar is responsive when the mouse hovers over it, indicates which page you are on (pink button), and fits with the pre-existing style of the app. It simply navigates between the two html files.


The Quiz UI - quiz.html

The quiz uses many jQuery commands to switch and change the display, according to the needs of the quiz. By default, there are 4 sections: the header, the card display, the filter, and the footer. The header is constant, and displays some information about the quiz, as well as the navbar and the contribute button.

The Header and The Filter
The filter is pictured above, labeled as Number of Books. This is a drop-down menu that filters the number of books to be quizzed on, from 5 to 50 at varying intervals, the code for which is shown below.
The Filter Code
The card display is just a div in the quiz.html file, it is filled programmatically by quiz.js.

The Card Display

The final part of the quiz.html page is the footer. The footer is changed programmatically through jQuery, however by default it shows the number of books selected and has a reactive button to submit your answers. Later it will be changed to display the score and give the user the option to tweet their score.

The Footer

The Quiz Logic - quiz.js

This is where the html document is edited heavily once the page is finished loading. There are many parts to this file, however I will summarize the functionality and show some examples of the code.

  1. The first part I worked on was to programmatically generate the cards from the data.js file, shuffle them, and display them in the div labeled "books". This part is largely recycled from emojipages main page, with a few additions in the shuffle function. I also added an editable div that functions as the text bar to enter your answer into. I added a variable to store a shortened, shuffled array, in order to provide functionality to the Number of Books filter.

  2. The second addition I made was the submission process. The user must type the title of the books based on the emojis into the editable divs in order to answer. They must then press submit and see their score. Green boxes indicate correct answers, and add to your score. Red boxes indicate incorrect answers, and will display the correct answer instead of yours.
  3. Entered a few titles
  4. Your score will be tallied and the footer will be changed using jQuery to show you your score, give you the chance to try again, and add a tweet button. The try again button simply reloads the quiz. 
The code for submission and footer
Indication of correct and incorrect answers, buttons change at the bottom

Interaction with brittanyrw

My interaction with Brittany was very different from pacdiv. I only talked to her once, and for the most part the only responses I've had are from bots. She has bots managing her three projects, and although she has many contributors on those projects, emojipages is her smallest with approx. 100 contributors as of writing. I'd imagine she's very busy and hasn't had time to take a look at my pull request, however I wish she would. At time of writing it's been 5 days. I'm going to try to get a hold of her again, as she still hasn't reviewed my pull request.

Problems that I had in this process

This project was an interesting experience and is still ongoing, however some of my issues so far have been:
  • My pull request has been submitted for 5 days and has not been reviewed yet.
  • Learning responsive css, jQuery, and html was a challenge, especially as I had to unlearn a few things first
  • Balancing this project with my courses (I have a capstone project that is moving very slowly + midterms)
  • Understanding where to draw the line on what files need to be touched. (ie creating new files instead of editing old ones, in order to avoid merge conflicts)
I continue to be optimistic about Hacktoberfest, as I look for my last 2 issues.


Thursday, October 3, 2019

Gatsby and Regex - My First Pull Request

regex.guide - An Easy Regex Building Tool

For my first pull request, I decided that I would look for a User Interface problem that was simple to solve so I could get used to the pull request process, I was looking for something familiar and comfortable, and what I found was different than what I expected. I had it very easy in Release 0.1 as I was working with friends and classmates. The internet is a very different place. In the end, I worked on an open source project called regex,guide.

Regex.guide, created by pacdiv is a tool for creating regex, by translating the requirements of you regex from an English sentence to a regex expression. It is a web-based front-end app programmed using GatsbyJS. GatsbyJS is an open source website framework that is based on React and creates static files to ease hosting.

But I'm getting ahead of myself, let's get to the real issue. The Issue.


Choosing the Issue

I searched for about 5 hours before I found something to work on, over the course of about 3 days. Every project that I found was either dead or completely out of my league. It wasn't until October 1st that I found something, due to the influx of issues aimed at hacktoberfest. Interestingly enough, the issue I found was not labeled Hacktoberfest. It was labelled "good first issue", and the label was correct. The issue was called "Add a reset button".

The issuer was pacdiv, who needed a reset button added to his regex guide app, created using the Gatsby framework, and written in Javascript and CSS. The reset button needed to be a transparent button, labelled "Reset Conditions" and must delete all current regex conditions selected, as the current method was to delete one at a time. I have included images of this process below. All that was left was to ask pacdiv if I could work on this issue. He allowed me to work on it and I got started.

regex.guide with 1 condition


regex.guide with 2 conditions, menu open to delete the second condition
regex.guide after deleting the second condition, menu open to delete the first

Preparation to Add the Reset Button

First, I needed to learn what Gatsby was. I know how to write Javascript and CSS files, but I had never heard of Gatsby. I learned that it was based on React, which I have used before. I am not the biggest fan of React, but I decided to move forward. It would be good to learn a new framework. What I learned is that Gatsby is simple and fast, but doesn't hold your hand as much as React and Angular do. I learned how to create components, routing, and how to use CSS with Gatsby. Finally, I learned how to set up my environment.

So after I forked and cloned the repository, I had to run npm install to get all the dependencies required to run the site. However, I couldn't get the site to run. This is when I discovered that Gatsby, like Angular and React ,has it's own development environment. I installed Gatsby globally, and was able to run the website with no issues. I started to familiarize myself with the contents of the app. After some searching I found the main component for the app, playground.js. Most of my work was to be done in this file. However I also needed access to core.js, which contained functions I needed and DefaultButton.js to get the CSS code I needed for my button.



The Solution and Pull Request

Version 1

I made a pull request once I was satisfied with the functionality. My first solution was to add a button, which on click ran a function called onResetConditionsButtonClick(). This function would called this.core's deleteConditions() function to delete each condition one at a time, until there was nothing left to delete. However, this code was a bit sloppy, and pacdiv needed a better version.
onResetConditionsButtonClick() function - first version

Version 2

The problem was that this function reset the entire app back to its original state, which didn't follow his original plans. Aside from that, the actual deleting should be contained in the core.js file itself, as it was already handling add, update, and delete operations. I followed his instructions and my second version removed most of this function, as well as removed the while loop altogether. I simply emptied the array of conditions instead, and that simplified my solution greatly. I have included the updated functions below, and the final look of the button itself:


onResetConditionsButtonClick v2

New Function in core.js: deleteAllConditions()

Button Design, pulled from DefaultButton.js

Version 3

Pacdiv wanted me to change the method of deletion back to array = []. I figure this method must fit his code better, so I've changed it to his specs. I also deleted another array that I didn't know needed to be deleted.

deleteAllConditions() v2

Interaction with pacdiv

I had a great experience interacting with pacdiv. I have no idea who this person is, but I like them. They were extremely professional and helpful. I asked them multiple questions and we discussed what made sense for the app in both my issue and pull request. We talked a lot about this "simple" reset button. Aside from a couple of other issues, things generally went well with my additions, and he seemed to like all of them. Our conversations exist across the issue and pull request links listed above. I would highly recommend working with this person, and I think I will continue to contribute to this project, as I really like pacdiv's idea.

As of now, my pull request is pending approval, so I will update this page if need be...


Problems that I had in this process

I had a great time working on this project but there were definitely problems that I faced:
  • I had difficulty finding an issue to work on
  • I had trouble getting the Gatsby app running on my machine, as I've already described.
  • pacdiv included prettier in his package.json file, which updated 53 files to different formatting. For some reason this only activated when I tried to push my version to Github, so for my pull request instead of changing 3 files, I changed 53 files. I didn't understand why until I asked pacdiv and he pointed me in the right direction
  • Gatsby was a lot like React, which I am not strong in. Instead I treated it more like HTML and didn't bother making a separate component for the reset button. I adapted to the situation using a familiar method.

Although I had some difficulties along the way, I look forward to the next pull request with confidence.


Friday, September 27, 2019

Hacktoberfest: My entrance to the 'Real' World of Open Source Development

DPS909, Hacktoberfest, and Release 0.2

Today I began to look at real issues and projects on Github. I've graduated from contributing to my peers' code, and have completed the first major project of four to be completed by the end of my course. Release 0.1 is complete, an assignment I talked about in my previous post. For the next assignment, I will have to attempt to complete the Hacktoberfest challenge. In order to win a Hacktoberfest T-Shirt, I have to find 4 issues and submit 4 pull requests on professional projects on Github. Part of the assignment is to blog my findings, so that is what I will be doing for the month of October.

My goals for Hacktoberfest

  1. To work on a product that I use frequently, and have my pull request confirmed and accepted to the project.
  2. To learn more about databases in a project that I work on, as I am very interested in database design.
  3. To contribute to a project that involves UI design, which I love to work on.
  4. To ask for help from my community and the online community as well.
So why am I attempting these goals? I want to engage in the community more, for a start. I keep to myself most of the time, and I have issues asking for help. It's one of the main problems I have in day-to-day life. I think this is a good opportunity to learn and grow in that respect. In terms of technical skill, I am fascinated by databases and their structure, and I want to learn more about them. I'm not sure what kind I'm going to find, but I'm excited at the prospect of contributing. Finally, my main goal is to contribute to a project that I use regularly. I am a frequent user of open source projects, but I never stopped to think how they were developed and why they are open source until now. I am hopeful that I can contribute to something I have used for so long.

Possible Issues

These are the issues that I am interested in attempting, for various reasons:

These two issues are good examples of easy entry code for me to try. I'm planning on finding something bigger to work on and having a few smaller issues going like these ones. Both of these issues are part of projects that are very interesting to me and are UI issues. To prepare myself to work on these I will brush up on my css, html, and javascript knowledge by reviewing my notes from previous years, and studying the styling of these projects in order to match colors, shapes, and sizes.
This project provides a way for me to combine my database and UI interests, in a feature that seems interesting to me. It involves creating a camera database to pull camera data from, in an effort to ease the processing of aerial imagery from drones. I could implement a database, and add a dropdown menu. In order to accomplish this, I must investigate the current database usage and features, how to implement such a database, and study the project's organizational structure and UI constraints.