Open Source for Beginners with Google Code-in

Google Code-in 2016 has already started and its a pleasure that I am a part of it this time working as a mentor with FOSSASIA on behalf on Public Lab which is working as a partner org with FOSSASIA. It is in its 7th consecutive year.

Google Code-in is a contest introducing pre-university students between the ages 13 to 17 to open source development. GCI takes place entirely online and is held during Winter every year during this time. The official dates are from 28 November, 2016 – 16 January, 2017 this time. Follow the timeline for detailed schedule. Winners get exciting goodies and T-Shirt from Google and a chance to visit the Google US office for a one week trip with their parents.

To many of you reading this post the word Open Source might be completely new. So let me start with very basics.

Every software that you use starting from your Operating system (Windows, Linux etc.) to any application, is written with some sort of code. So the beautiful and mind blowing applications that you use in your computers or mobiles is the hardwork of some awesome developers who write this code. So many of you out there might have a curiousness to look behind the code that caused it. But not all software are “Open Source” meaning not all of them provide you access to their code.

Open source Software means software whose code is available to all. You can use it, modify it and distribute it ( subject to the License provided along with it ). And the most awesome part is you can actually contribute to it and help it to improve.

Now the most important question. How to actually contribute to Open Source ?  The task may look daunting seeing the millions of lines of code beneath. But believe me it’s actually fun once you get started with it. And what you will love the most about Open Source once you land in it is that you will always find people to help you. So Open Source isn’t just lines of code, it refers to the whole community who preach it and are involved with it. And once you get started with it you will actually fall in love with it.

So if you are completely blank about Open Source ( or already a Open Source contributor ) and want to know more about it and meet the criteria ( between 13 and 17 years of age ) Google Code-in 2016 is just the best place for you to get started.  You don’t have know about Coding even to get started. There are many beginner and non-Coding tasks to make you acquainted to Open Source. So why wait ? Just register yourself for Google Code-in 2016 !

How to Get Started ?

These are few basic steps that you should follow

  1. Create an account on Github
  2. Read the Guides and About Section in Google Code-in website. Be aware of the Timeline.
  3. Register yourself on Google Code-in site
  4. Search for an Organization like FOSSASIA ( which I am mentoring for )
  5. View tasks and choose a Task labelled Beginner to get  started
  6. Claim the Task and follow the instructions provided to complete it
  7. Get it reviewed by the Mentor

What you need to Know ?

Well there’s nothing much you need to know. There are many non-Coding tasks like writing blog posts, making a video, improving documentations. So you really don’t need to know anything except doing conversations in English which is a must as it is the medium of Conversation since it is an worldwide event. It is specially designed to encourage new comers to Open Source and make them learn. But if you already know Coding in any scripting, programming and markup language it is a plus point and you can approach coding tasks. Even if you don’t know Coding it’s completely OK as you can start learning from here.

A short introduction to Git and Github

Well this is a lot of talk and if you recall I mentioned it is completely online and you work from home. But did you wonder how can you actually work on the same piece of code sitting at remote places when you have so many people working on the same code? Won’t it get all messed up when people try to change things at the same time ( at the same line of code to be specific ). So here comes the concept of Version Control System which actually helps to deal with this and Git is a software that helps in Version Control. You don’t need to get scared as this is nothing but a way to work with different versions of code existing with each user after changes are made. To learn more on it just wait for my next blog Post. And this is something that you need to learn in Open-Source as it is used eveywhere in Open-Source and you will get to learn it at some point in Google Code-in.

As for Github it is the largest git hosting website in the current Date. In simple terms it is the place hosting the largest number of Open Source Projects often called the developers Hub. So if you want to work on a wide variety of Open Source projects Github is the place where you will find them. The smart Octocat logo is the most seen thing that you will become familiar with as you become an Open source developer.

Finally A GSoCer!

Finally! I successfully passed the Final Evaluation! Just can’t mention how happy I am! As I woke up on the Tuesday morning on August 30th I found this mail from gsoc

final

And I was just feeling great with a sense of accomplishment and that the hardwork I did for the last 3 months brought results! It was a great experience contributing to open source all this time and now I have considerable amount of contribution.

Though I was quite sure about my evaluation as my mentor Jeff already appreciated my work in a comment in my Final wrap up note prior to the official result declaration and I found he wrote the same thing in my Final evaluation as well 🙂

Thanks to my mentors Jeff, Liz, Stevie, Bryan and David and the entire PublicLab team! It  was a great experience working with all of them. They were really helpful working with all of the GSoC students and providing regular feedback. I hope I get to work with them more. We will be having a video call with all the gsoc students and mentors soon. They call it Openhour and it is a kind of online seminar that they have in the beginning of each month and the September Openhour is dedicated to the gsoc students. Excited for that!

This is just the starting of something good and I hope I can contribute more to open source and learn new stuffs and share my experiences here!

And as the famous poem by Robert Frost says:

And miles to go before I sleep,
And miles to go before I sleep !

The PublicLab Rich Editor

The twelfth week marker! The beginning of the end! GSoC 2016 will soon come to an end. I am almost done with my work on the Q & A system though some work is still left as per my timeline goals. The only major work that remains is integrating the PublicLab Rich Editor for use in the Q & A system.

The PublicLab Rich Editor is a separate project in PublicLab that my mentor Jeffrey Warren has been working on. It is an Editor that supports both markdown and WYSIWYG content. It is to be integrated in the publiclab.org website for posting content very soon. As a part of Q & A project I thought of working on it a bit and contribute as much as possible. It wasn’t initially included in the timeline when I initially made my proposal but later I modified my timeline to include it as it really seemed interesting.

The  PublicLab Rich Editor is a s a general purpose, modular JavaScript/Bootstrap UI library for rich text posting, which provides an author-friendly, minimal, mobile/desktop (fluid) interface for creating blog-like content, designed for publicLab.org. It uses grunt for packaging and compilation. It has a rich text editor based on the Woofmark library and an autocomplete  feature  supported with horsey library. It uses jasmine as its testing framework.

Since I am not familiar with Nodejs or npm it is a bit tough for me to understand its modular structure. I still didn’t make any contribution to the Rich Editor. But I will likely make some contribution as the program wraps up. Have to learn Nodejs for this. I also have to work on fixes that come up during the last week as things are going to be deployed in the live site.

Also my team mates who were working along with me in the same website but different project are doing some awesome work and there is big merge on the Search project that is coming up. So things are getting busy in plots2 in the upcoming week. Stay tuned as the GSoC 2016 comes to an end!

Modified Views for publiclab.org – Expanded Q & A Project

The end of the eleventh week in GSoC 2016 and when I look back I am amazed to see the amount of contribution that I made to plots2. For the last couple of weeks I  have been working on designing the interface for some pages, mainly the changes due to the Q & A system. Here are what I have been working on till now

  1. Add a Recently Answered tab in questions landing page that lists out the recently answered questions
  2. Add Q & A to user Profile that would list the questions asked and answered by any user
  3. Create a a distinct sidebar for questions
  4. Add a tag based sort functionality for questions. This would enable filtering questions based on tags
  5. Add a separate question tab in tags page. Tags page contained research notes, wiki and maps earlier
  6. Make it easier to search and ask questions from the questions page by improving the Search/Ask question field that I made earlier.
  7. Finally add links for Questions page in the website header and also put links to Question page and Ask question page in various pages like the dashboard, tags page etc.

This is going to be long PR and I am still working on it; it is nearly completed. Just some little design changes and modifications are needed.

Apart from these there were some important issues that I had to take care while making these changes. I had to distinguish between research notes and questions since questions in plots2 were actually notes marked with a question:topic power tag. So I had to list out research note and questions separately. I made two methods .research_notes() and .questions() in the DrupalNode model that would extract research_notes and questions separately.

Apart from these there were many small design changes that I had to make alongside. Here are some of the screenshots of the pages. They are likely to  be changed in future.

Here is how the questions page looks now when you go to the /questions url

questions

Here is how the content of the questions section in profile page would look. You can see this in the /profile/:username url

user_profile

And here is how the questions will be listed in the /tags/:tagname url

tags

You can find my ongoing work on plots2 PR #628

 

Creating Custom Rake Tasks

As I write this the tenth week in GSoC 2016 is over and it’s the end of the month now. I am a little late with my timeline mostly because I am doing work on the web interface for some pages and things need  to be changed over and over to fit the design choices. But in the mean time I got to learn something new. We had to run two separate rake tasks for running rails tests and JavaScript tests. So there was an issue to run all tasks with one rake task for ease. This is where I learnt about creating custom Rake tasks.

Rake is a Make-like program implemented in Ruby. It comes as a Rubygem and has to be included in your Gemfile during development. Custom Rake tasks start with a namespace followed by the task name separated by a colon. They reside in the lib/tasks directory of a rails app and they go in a file with a .rake extension.

Here is the railsguides documentation on How to create  Custom Rake tasks. Here is this good blog post by ANDREY KOLESHKO while I learnt about writing rake tasks. As you can see there you can either directly write the task in the namespace.rake (remeber to name the file same as the namespace ) file in the lib/tasksdirectory or you can use the rails generator to create the task file

$ rails g task my_namespace my_task

This will create a lib/tasks/my_namespace.rake file where you can write your task.

I needed to run the two tasks rake test and rake spec:javascript from this task. So basically I had to run rake tasks from within a rake task. Here is a stackoverflow answer that answers it perfectly! Know the difference between execute, invoke and reenable.

Here is a custom task I wrote. It can run using rake test:all


# rake test:all
namespace :test do
desc "Run rails and jasmine tests"
task :all do
puts "Running Rails tests"
Rake::Task["test"].execute
puts "Running jasmine tests headlessly"
Rake::Task["spec:javascript"].execute
end
end

view raw

test.rake

hosted with ❤ by GitHub

You can find this in the commit e90fe of plots2. I would be probably posting about the work on design changes in my next post.

Keeping Rails models DRY with concerns

Its over the ninth week in GSoC 2016 and here I am with another of my blog post. Today I will discuss about a pretty nice thing that I learnt while I was working with the notification system. It is related to writing DRY code by using of modules.

My mentor Jeff said that methods in some models were becoming repetitive and they were doing the same kind of task. So it would be better if we could keep the code DRY i.e. avoid redundancy in code. DRY stands for Don’t Repeat Yourself i.e. try to avoid repetitive code in a application. We can do this by  creating methods and modules. Ruby has an awesome concept of modules and mixins  for this purpose.

ActiveSupport Concerns follow the same principle  of Ruby modules and by extending them on Rails models we can include common methods that are shareable across various models.

We had two models named Node and  Answer models. A Node basically served as a container of posts like wikis, questions and research notes in publiclab.org. Answer as the name suggests are answers to questions. Both have some common methods named liked and liked_by. So we made a NodeShared concern and put those in them. Here is how the concern looks like


module NodeShared
extend ActiveSupport::Concern
def likes
self.cached_likes
end
def liked_by(uid)
self.likers.collect(&:uid).include?(uid)
end
end

view raw

node_shared.rb

hosted with ❤ by GitHub

This file goes in a separate app/models/concerns/directory. This is where all concerns reside. To define it as a concern you need to extend the ActiveSupport::Concernmodule as I did above. After that after you have defined the concern you can use it in others models by including the concern like include NodeShared in this case. Here is how the node model would look


class Node < ActiveRecord::Base
include NodeShared # This includes the NodeShared Concern
attr_accessible :title, :uid, :status, :type, :vid, :cached_likes, :comment, :path, :slug
self.table_name = 'node'
self.primary_key = 'nid'
has_many :node_selections, :foreign_key => :nid
has_many :answers, :foreign_key => :nid
def latest
self.revisions
.where(status: 1)
.first
end
def revisions
self.drupal_node_revision
.order("timestamp DESC")
end
end

view raw

node.rb

hosted with ❤ by GitHub

This is a small part of the actual model used. So now the methods in the concern become a part of the model and they can be called with an instance of Node model. Now suppose the Answer model also needs the similar methods. We can simply add this concern to the model as well instead of writing the methods over again.

DHH the creator of Ruby on Rails explained this in his blog post.

Coming back to my progress in Summer of Code I have started working on UI changes and modified views that will include some good features. I will discuss them in my future posts. You can look at my PR #628 though it is Work in progress now. As the mid of July is over its probably going to be more work in the next couple of weeks as things are nearing the end.

Email notifications using Rails ActionMailer

The eighth week of GSoC 2016 coding period is over and I got to work on something new in Rails. This time I was making the email notification system for the Q & A system so that when a user posts a question or answer related people get notified via emails.

Rails has has email delivery framework called ActionMailer. Though I was familiar with Rails, I haven’t worked on ActionMailer before this. So the first thing to do was checking the ActionMailer documentation. I strongly recommend following this  documentation to  understand the email delivery system. Rails guides have good documentation for each version of Rails and the features well explained. It’s a good place to start with.

I had to create a new AnswerMailer and modify the existing CommentMailer and SubscriptionMailer to send out email notifications to users.

A Mailer basically contains some methods that defines the recipient and the subject of the mail to be sent along with the delivery method. It inherits from ApplicationMailer which basically contains the default sender mail address. The mailer view template goes under the views directory which is the standard template directory for Rails. The view template is named according to the mailer method. So for AnswerMailer if there is a method named notify_question_author the template would go with the name notify_question_author.html.erb in the views/answer_mailer directory. Whatever content you want to send in the email goes in this email. So you see the naming convention and functioning quite is similar to Rails controller though not the same.

To send a mail you need to call the mailer method from the controller as described here. Now you need to send mail on specific conditions. Like when you create a post, for example, you would want the subscribers to get specific content while when you post an answer to a question you would like to notify the question followers as well who asked the question. So it is good to create a class or an instance method in related model to do so. Like I defined a instance method answer_notify() for Answer model that notifies the question author as well  as users who liked the question. This contained  two mailer methods AnswerMailer.notify_question_author() and AnswerMailer.notify_answer_likers() which sent emails on meeting some specific conditions. So this way you can frame a custom method that sends the mail and suits the conditions as well keep the code in the controller simple an let the Model contain the method description.

You can find my entire work on this in plots2 PR #612.

Testing with Jasmine

This marks the seventh of GSoC 2016 and a lot of work has been merged since I started working. Looking back at it gives real feeling of accomplishment.

An important part of writing good code is that it is well tested. So that when you start working on a new feature or a fix you ensure that it doesn’t break any functionality by running the tests. Having a good test suite ensures your app has a strong backbone and it also can be extended for further development.

We have been writing rails tests for quite sometime and now we have good test suite for plots2 . But we didn’t have any test framework for testing JavaScript functionalities. So my mentor Jeffrey Warren suggested that we have tests for JavaScript too. We chose the Jasmine framework as it is the most popular JavaScript framework used and it also comes out in different packages for in browser testing and npm package as well as a rubygem as well for headless command line testing powered by phantomjs. And the best thing is it is best suited for Rubyists as the testing pattern is similar to Rspec – the popular Ruby testing framework. Here I am going to brief on how to setup Jasmine using the jasmine-rails gem. Since we were mostly using jQuery for JavaScript functionalities we also used the jasmine-jquery-rails gem to enable use of html-fixtures and some custom matchers.

Setup jasmine-rails

Follow the installation instructions to install the jasmine-rails gem to use it in your test-suite. This should also install the phantomjs gem along with it. But if the package installation fails you follow this documentation given here. A  spec/javascripts  folder will be created where all test files will reside.

You can run tests headlessly using the command

rake spec:javascript

 

How to write Tests ?

Now the most important how to actually write tests? The best place to start is with the jasmine docs. It gives a comprehensive guide to how to write tests. Jasmine tests basically describe a test and set some expectations which are tested against some matcher. All tests are written in spec files which are basically js files that reside in the spec/javascripts folder. Let us take a very simple test. As you can see it is written in a js file jasmine_spec.js


describe("A suite", function() {
it("contains spec with an expectation", function() {
expect(true).toBe(true);
});
});

view raw

jasmine_spec.js

hosted with ❤ by GitHub

Here the describe() function start a test description with a string and a function that contains a block of code. The it block also starts with a string and a function that contains a code block that contains expectations. The describe block basically tells the bigger story. And the it block tells the smaller individual stories that need to be tested. The expect() functions defines the expectation that is to be made. It can contain any instance or message. Basically any variable or method that returns something should go in it. The expect()function goes with a matcher chained with it. Each matcher implements a boolean comparison between the actual value and the expected value. It is responsible for reporting to Jasmine if the expectation is true or false. Jasmine will then pass or fail the spec. Here toBe() is a matcher.

Faking Ajax Calls

Now there are Ajax calls in applications that require server side requests. But depending on server responses makes the test suite slow and also leads to test failures when offline. So to test Ajax we need to fake Ajax calls using mock-ajax. You can simply copy paste the code in this link and put it in a helpers/mock-ajax.js file that goes inside the spec/javascripts folder. To mock ajax calls across a test suite you need to use install() and uninstall() in beforeEach()and afterEach() blocks in the beginning of the describe block as explained in the documentation. This sets up jasmine-ajax across the test suite. You can have a look at the jasmine-ajax documentation to have an idea on how to fake ajax calls.

Basically what happens in the entire process is you make or trigger a Ajax request first. Then you need to “Spy” on the Ajax call and return a fake Ajax response.  After that you need to test that with the expectation. A Spy is nothing but a function that helps faking the response. It is similar like a stunt double of an actor who fakes for the actor for a shot in a movie! You can learn more about Spies here. I was using jQuery and was using the .ajax() function for ajax calls so i preferred this stackoverflow answer to fake the ajax response.

Now you have been thinking what’s the point of testing if we actually setup the fake response  ourselves and test the same. Its definitely going to pass! Well  it’s not going to pass unless you have your Ajax call working properly. The entire point is not testing the response but whether the Ajax call is actually triggered on executing the action. The response is tested in the server framework, here, the Rails test suite.

Using HTML fixtures

When you are testing JavaScript in a web application you must have it associated with some html element may its a button or a link. What you want is to test it against some event like a hover or a button press specifically those associated with an Ajax call. What you need to do is to create a html file with that specific element like the button or link similar to what you have written in the actual page and load it in the test suite. HTML fixtures go in a separate fixtures directory inside the spec/javascripts directory. Here is a sample fixture I wrote .


<ul class="btn-group">
<li rel="tooltip" title="Helpful? Like it and get updates!" class="btn btn-default btn-sm btn-like" node-id="1" id="like-button-1"><span id="like-star-1" class="fa fa-star"></span> <span id="like-count-1">1</span></li>
</ul>
<script>
jQuery(document).ready(function() {
$('#like-button-1').on('click', clickliked);
})
</script>

view raw

unlike.html

hosted with ❤ by GitHub

As you can see I also associated the event associated with the button so that I can trigger the button press in the test.

To load the fixtures include the fixtures path at the top of the describe block

jasmine.getFixtures().fixturesPath="../../spec/javascripts/fixtures";

Also if you are using jasmine-jquey you need to preload the fixtures by including this line

preloadFixtures('unlike.html')

Finally load the fixture at the beginning of the specific test in the it block

loadFixtures('unlike.html');

Now you can use the html elements in the test. Like you can trigger the button click using

$('#like-button-1').trigger('click');

That’s how you use fixtures in test.

Whenever you have a problem in testing try debugging using a console.log() message. That helps you in figuring where you are going wrong in the test.

Here is how a spec file would look. You can find my work on this in plots2 PR #618.

GSoC 2016: The Next Phase

I finally made it through the Mid-term evaluations of GSoC 2016! It makes me happy to have made it this far but it’s still not over yet. Moving on to the next phase of GSoC. This ones going to be important as it is longer than the first phase and also I have some pretty good features that I had planned out in my timeline. Here is what I have been working in the past week after the Mid-term evaluations. But before I go to that I want to show you what my mentors gave me as feedback during my Midterm evaluation.

midterm

Really some praising words! Its things like these that really motivates to go on with my work. And that’s an essence of open source too! If you are working with the right community, people really help you out and you get the word of appreciation.

The next feature I have been  working on is making an Accept button for answers. This makes it possible for the author the question to mark an answer as accepted. The “accepted” answer would be marked with a green label  when it would be accepted. The question author can also unaccept it by pressing the same button again. Here is the screenshot of how it would look.

accept_answer

The complete work can be found in the plots2 PR #598