Our current assignment is to read two articles from opensource.com and blog our response to these articles.
Sebastian Dziallas' article, How to Teach Undergrads How to Become Open Source Contributors Without Writing Any Code, caught my attention because it involves a different approach to teaching open source. As a computer science major, it makes sense to include coding as part of the core open source experience in a software engineering class; however, not all contributors to open source projects are programmers. Chapter 8 in Teaching Open Source describes the importance of documentation and technical writing. There are many opportunities to contribute to these vibrant open source communities outside of the realm of coding, but it seems as though very few classes offer a glimpse into this alternate perspective.
Dziallas' Release Engineering course started as somewhat of an experiment, and it developed into a highly educational experience. From his descriptions, projects went better than expected, and students were given the chance to see Tom Callaway, the Fedora Engineering Manager, talk in person about some of the same issues that Dziallas mentioned in class. I would like to see more opportunities for people to branch out and explore the world of open source. Dziallas mentions that he has been working with Fedora since he was 16. I am only beginning my adventure at the age of 21, but I am glad to have this opportunity.
Another article that sparked my interest is Anthony Biller's A Cure for the Common Troll. I mentioned much earlier in my blog that I read tech-blogs, such as engadget and gizmodo, on a daily basis. I have not seen as much mention of it lately, but, for a while, lawsuits concerning patent infringements dominated the headlines. Samsung and Apple battled it out constantly over, what is in my opinion, trivial matters. The authors of these posts and many of the readers pointed out that this incessant bickering is a common marketing scheme to help fill the coffers when business is slow.
The trolls that Biller mentions go above and beyond the previously mentioned form of trolling. "Patent trolls," as he calls them, hold patents to technologies and manufacturing processes that they will probably never use. Some trolls make six to seven digit figures based on abusing the patent system alone. Apple has been known to patent anything and everything that they can, but the real patent trolls have no real plans with these patents other than threatening other companies and making an absurd amount of money in the process. I am not a big legal buff and do not understand all of Biller's suggested solutions, but his first solution seems to plug a major loophole in the patent system. Without vague "umbrella" patents that cover every possible domain, patent trolls would have a much harder time abusing the system.
Tuesday, February 28, 2012
Day Twenty: An Update on our Group Progress
My group met at our usual time and place on Sunday to discuss our accomplishments and decide what to work on over spring break. Matt Vaveris and I decided to focus on bug #12653. This bug involves an Xbox 360 controller, and we both have access to such a controller. Julie will focus on bug #12594 because her laptop has a built-in Blu-Ray drive. David is looking into bug #12699 because the bug report itself is difficult to read. If the broken English cannot be deciphered, the report is useless and needs to be deleted. Jason was not able to attend the meeting, but he can work with David or Julie depending on the level of progress that is made respectively.
I was able to reproduce my bug on two different systems running Windows 7 with the latest updates. My laptop, running XBMC Eden Beta 2, experienced a crash exactly as the reporter described. Here are the steps to recreate:
I was able to reproduce my bug on two different systems running Windows 7 with the latest updates. My laptop, running XBMC Eden Beta 2, experienced a crash exactly as the reporter described. Here are the steps to recreate:
- Plug in the controller and make sure that it is on (you need the appropriate drivers for Windows to recognize it).
- Start XBMC
- Unplug the controller and Alt+Tab out of XBMC
- Wait 3-4 minutes
- Bring focus back to XBMC
I tried this process again on my desktop PC, running XBMC Dharma, with a wireless Xbox 360 controller, and I experienced the same crash. I want to contribute to this bug report with my findings, but the webmaster for the XBMC forums must not be receiving my messages for some reason. The forums still mark me as a spammer, regardless of my email address (I have tried yahoo and multiple gmail accounts). Luckily, Matt has a username, so he can do the talking for us. It is surprising that a bug like this has persisted through Dharma and three beta builds.
Day Nineteen: Explaining the Code
Chapter 8 in the Teaching Open Source textbook is all about documentation. The information in this chapter is easy enough for a newcomer to understand, and it acts as a refresher for more experienced individuals.
Exercise 8.1.1: Practice Good Code Commenting
My team's first contribution to XBMC is an updated readme file with information that was simply left out and referenced in the forums. This is exactly the kind of thing that chapter 8 talks about. The information is there somewhere, but it is rarely easy to find. A well documented project simply takes all of the sources (mailing lists, IRC discussions, and wiki pages) and makes them readable and easily accessible. Open source projects are more approachable if they document this information for new and old users/developers alike.
Exercise 8.4: Plan Your Technical Document
The Nexus Mod Manager (NMM) that I mentioned in a much earlier blog post finally has some documentation in the form of a wiki page here. I still use NMM to this day for all of my Skyrim mods. Steam's workshop seems like a decent alternative, but I still feel attached to the nexus community. My plan was to add a wiki page that documents how to add non-NMM mods, but it appears that another user meatwad2021 already has this idea in mind. Under the "discussion" part of the wiki, meatwad has this to say:
"Considering the chaos that has ensued with Nebula's Skyrim HD 1.5 pack conversion from loose file style to the .bsa/.esp packaging, I've been creating a few new pages dealing with 7zip and SKSE. The next step is to teach users how to deal with files not offered with the Download with Manager option as is required for Nebula's 1.7Gb update. Sooooo, I'm going to take a crack at addding that section here to the existing page."
This update was posted on the 25th, so I might try to contact him and see if he would like some help. Even though my group chose XBMC as our FOSS project, I would still like to contribute to the Nexus community in some way.
Exercise 8.1.1: Practice Good Code Commenting
My team's first contribution to XBMC is an updated readme file with information that was simply left out and referenced in the forums. This is exactly the kind of thing that chapter 8 talks about. The information is there somewhere, but it is rarely easy to find. A well documented project simply takes all of the sources (mailing lists, IRC discussions, and wiki pages) and makes them readable and easily accessible. Open source projects are more approachable if they document this information for new and old users/developers alike.
Exercise 8.4: Plan Your Technical Document
The Nexus Mod Manager (NMM) that I mentioned in a much earlier blog post finally has some documentation in the form of a wiki page here. I still use NMM to this day for all of my Skyrim mods. Steam's workshop seems like a decent alternative, but I still feel attached to the nexus community. My plan was to add a wiki page that documents how to add non-NMM mods, but it appears that another user meatwad2021 already has this idea in mind. Under the "discussion" part of the wiki, meatwad has this to say:
"Considering the chaos that has ensued with Nebula's Skyrim HD 1.5 pack conversion from loose file style to the .bsa/.esp packaging, I've been creating a few new pages dealing with 7zip and SKSE. The next step is to teach users how to deal with files not offered with the Download with Manager option as is required for Nebula's 1.7Gb update. Sooooo, I'm going to take a crack at addding that section here to the existing page."
This update was posted on the 25th, so I might try to contact him and see if he would like some help. Even though my group chose XBMC as our FOSS project, I would still like to contribute to the Nexus community in some way.
Day Eighteen: RMH Homebase Continued
After wasting countless hours on a virtual machine running Ubuntu 10.04 and another virtual machine running Ubuntu 11.10, I finally got RMH Homebase to work on the 11.10 virtual machine. A fellow classmate of mine posted an install guide to his blog here. Although I followed very similar steps during my own installation attempts, his guide corrected whatever I was doing wrong.
The assignment for today is exercise 5.7 and 5.8 in the Software Development book.
Exercise 5.7: Debugging
As the book mentions, there are two places in RMH Homebase that display a shift's "notes" field for editing, calendar.php and calendarFam.php. Both of these modules include calendar.inc, so refactoring this "bad smell" should be as simple as adding a function to that file and replacing the old code with a function call. I added the following function to calendar.inc:
function predates($a, $b) {
return ($a->get_year()<$b->get_year() || ($a->get_year()==$b->get_year() && $a->get_day_of_year()<$b->get_day_of_year());
}
This function will return true if a's year is less than b's year or, in the case where both a and b are during the same year, a's day of the year is less than b's day of the year. In other words, this function returns true if a predates b. Unfortunately, the test file"testCalendar.php" is not present in my tests folder. I will have to hold off on unit testing until I can find a copy of this file or make a file of my own.
Exercise 5.8: Examining the Code
A. Sub Call Lists (SCLs) are viewed and edited through functions included in the module subCallList.php. In editShift.php, either "View Sub Call List" or"Generate Sub Call List" is displayed depending on whether the shift has an associated SCL or not. Here is the code:
if(!$shift->has_sub_call_list() || !(select_dbSCL($shift->get_id()) instanceof SCL)) {
echo "<input type=\"hidden\" name=\"_submit_generate_scl\" value=\"1\"><br>
<input type=\"submit\" value=\"Generate Sub Call List\" name=\"submit\"style=\"width: 250px\">";
}
else {
echo "<input type=\"hidden\" name=\"_submit_view_scl\" value=\"1\"><br>
<input type=\"submit\" value=\"View Sub Call List\" name=\"submit\" style=\"width: 250px\">";
}
As you can see from the if-else statement, not every shift has a sub call list.
B. Archived weeks are weeks that are set to the status "archived". The status can be set using the function set_status($s) to "unpublished," "published," or "archived." Calendar.php includes a statement that does not allow archived weeks to be edited by anyone. I cannot find any modules that call set_status($s). I only see if statements that check to see whether a week is archived in order to hide it from view.
The assignment for today is exercise 5.7 and 5.8 in the Software Development book.
Exercise 5.7: Debugging
As the book mentions, there are two places in RMH Homebase that display a shift's "notes" field for editing, calendar.php and calendarFam.php. Both of these modules include calendar.inc, so refactoring this "bad smell" should be as simple as adding a function to that file and replacing the old code with a function call. I added the following function to calendar.inc:
function predates($a, $b) {
return ($a->get_year()<$b->get_year() || ($a->get_year()==$b->get_year() && $a->get_day_of_year()<$b->get_day_of_year());
}
This function will return true if a's year is less than b's year or, in the case where both a and b are during the same year, a's day of the year is less than b's day of the year. In other words, this function returns true if a predates b. Unfortunately, the test file"testCalendar.php" is not present in my tests folder. I will have to hold off on unit testing until I can find a copy of this file or make a file of my own.
Exercise 5.8: Examining the Code
A. Sub Call Lists (SCLs) are viewed and edited through functions included in the module subCallList.php. In editShift.php, either "View Sub Call List" or"Generate Sub Call List" is displayed depending on whether the shift has an associated SCL or not. Here is the code:
if(!$shift->has_sub_call_list() || !(select_dbSCL($shift->get_id()) instanceof SCL)) {
echo "<input type=\"hidden\" name=\"_submit_generate_scl\" value=\"1\"><br>
<input type=\"submit\" value=\"Generate Sub Call List\" name=\"submit\"style=\"width: 250px\">";
}
else {
echo "<input type=\"hidden\" name=\"_submit_view_scl\" value=\"1\"><br>
<input type=\"submit\" value=\"View Sub Call List\" name=\"submit\" style=\"width: 250px\">";
}
As you can see from the if-else statement, not every shift has a sub call list.
B. Archived weeks are weeks that are set to the status "archived". The status can be set using the function set_status($s) to "unpublished," "published," or "archived." Calendar.php includes a statement that does not allow archived weeks to be edited by anyone. I cannot find any modules that call set_status($s). I only see if statements that check to see whether a week is archived in order to hide it from view.
Saturday, February 25, 2012
Day Seventeen: Group Planning
My group met at our usual time last Sunday and made a general outline of our schedule for the rest of the semester. I created and shared a Google calendar with every group member, so it is easy for any of us to edit any important events. We hope to address four additional bugs over the course of the semester and save a week or two for preparing a poster and the final presentation. A link to our schedule can be found here.
Back to RMH Homebase
I tried to get RMH Homebase running on my Ubuntu 10.04 virtual machine, but I am having difficulties with the MySQL server. Apache seems to be working fine, and PHP5 is pretty straight forward. I am not certain that MySQL is where my install fails, but it is the most likely cullprit. I will walk through the steps I took to install for reference. A link to the most helpful webpage that I found is here.
Download RMHHomebase 1.5 from the sourceforge page
Install tasksel and then the LAMP stack
$ sudo apt-get install tasksel
Set MySQL root password
$ mysql -u root
At the mysql console type:
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('yourpassword');
mysql> CREATE DATABASE rmh15DB;
mysql> GRANT ALL PRIVILEGES ON *.* TO 'yourusername'@'localhost' IDENTIFIED BY 'yourpassword' WITH GRANT OPTION;
mysql> \q
Install phpMyAdmin
$ sudo apt-get install phpmyadmin
Back to RMH Homebase
I tried to get RMH Homebase running on my Ubuntu 10.04 virtual machine, but I am having difficulties with the MySQL server. Apache seems to be working fine, and PHP5 is pretty straight forward. I am not certain that MySQL is where my install fails, but it is the most likely cullprit. I will walk through the steps I took to install for reference. A link to the most helpful webpage that I found is here.
Download RMHHomebase 1.5 from the sourceforge page
Install tasksel and then the LAMP stack
$ sudo apt-get install tasksel
$ sudo tasksel install lamp-server
Set MySQL root password
$ mysql -u root
At the mysql console type:
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('yourpassword');
mysql> CREATE DATABASE rmh15DB;
mysql> GRANT ALL PRIVILEGES ON *.* TO 'yourusername'@'localhost' IDENTIFIED BY 'yourpassword' WITH GRANT OPTION;
mysql> \q
Install phpMyAdmin
$ sudo apt-get install phpmyadmin
$ sudo nano /etc/apache2/apache2.conf
note: add "Include /etc/phpmyadmin/apache.conf" to apache2.conf
Follow the directions in README1.5.pdf
Day Sixteen: Bad Smells
Exercises 5.1-5.3 in Software Development: An Open Source Approach involve finding and fixing various "bad smells" in the example software, RMH Homebase. As with most open source exercises, the first step is to download the source code. Install Mercurial and checkout RMH Homebases' repository on sourceforge.
$ sudo apt-get install mercurial
$ hg clone http://rmhhomebase.hg.sourceforge.net:8000/hgroot/rmhhomebase/rmhhomebase
Find and fix the "Bad Smells"
Long Method: A method should do one thing and only one thing. addWeek.php violates this rule of thumb by accepting various parameters, such as publish, reset, and remove in order to change the main function's actions.
This code tries to do three different actions in one function. The easiest fix is to separate these actions into their own functions. The goal is to have high cohesion.
Too Few Comments: Having looked through most of the code, it is safe for me to say that this software has too few comments overall. Some files, such as personEdit.php, have a decent number of comments. The comments do a good job explaining "why" instead of "how" something is done. A pair of fresh eyes can look at personEdit.php and get a sense of what is happening and why is it important. In my Operating Systems class, students are encouraged to comment all but the most obvious lines of code. An instance variable "counter," when used with a loop, is obviously a counter. Commenting every line would classify as too many comments, and this is also a "bad smell." personEdit.php finds a point in the middle of both extremes.
Other files, such as editMasterSchedule.php, only have a few comments for hundreds of lines of code. Maintenance accounts for a large percentage of a software's life cycle; therefore, good documentation is necessary in order to reduce maintenance costs and avoid future hassles. The function get_day_names() in editMasterSchedule.php is a simple example of too few comments. Monday through Friday are determined through a very similar process via if statements, but Saturday introduces a substring method that is not used for any other day of the week. Why? If there is something intrinsically different about Saturday that requires it to be handled differently than a weekday, a comment should reflect that. Given a few months, it is difficult to forget even your own code. Comments increase readability and reduce maintenance costs. It might take a few extra seconds to type a comment, but the benefits are well worth this extra coding time.
Data Clumps: A data clump occurs when several variables consistently appear together. The only data clump that I can find in this code is related to the date. Month, day, and year are kept together in a date object, but the string name and three character abbreviation are also used to identify days. The function get_day_names in editMasterSchedule.php assigns these string identifiers manually, but this could easily be done in a custom date object.
Speculative Generality: Speculative generality is defined as "inserting features into the code for functionality that is not part of the current requirements." Having looked over chapter 5, appendix A, and RMH Homebase's source code, I have not noticed any included features that are not part of the requirements.
$ sudo apt-get install mercurial
$ hg clone http://rmhhomebase.hg.sourceforge.net:8000/hgroot/rmhhomebase/rmhhomebase
Find and fix the "Bad Smells"
Long Method: A method should do one thing and only one thing. addWeek.php violates this rule of thumb by accepting various parameters, such as publish, reset, and remove in order to change the main function's actions.
if($_GET['publish'] && $_SESSION['access_level']>=2) {
$id=$_GET['publish'];
$week=get_dbWeeks($id);
if ($week->get_status() == "unpublished")
$week->set_status("published");
else if ($week->get_status() == "published")
$week->set_status("unpublished");
update_dbWeeks($week);
add_log_entry(''.$_SESSION['f_name'].' '.$_SESSION['l_name'].' ' .
$week->get_status().' the week of get_id().'&edit=true\">'.$week->get_name().'.');
echo"Week \"".$week->get_name()."\" " .
$week->get_status() . ".
Back";
}
// resets a week if the user is a manager
else if($_GET['reset'] && $_SESSION['access_level']>=2) {
$id=$_GET['reset'];
$week=get_dbWeeks($id);
delete_dbWeeks($week);
add_log_entry(''.$_SESSION['f_name'].' '.$_SESSION['l_name'].' reset the week of get_id().'&edit=true\">'.$week->get_name().'.');
generate_populate_and_save_new_week(substr($id,0,2),substr($id,3,2),substr($id,6,2),
$week->get_weekday_group(),$week->get_weekend_group(), $week->get_family_room_group());
echo "Week \"".$week->get_name()."\" reset.
Back";
}
else if ($_GET['remove'] && $_SESSION['access_level']>=2) {
$id=$_GET['remove'];
$week=get_dbWeeks($id);
if ($week->get_status()=="unpublished" || $week->get_status()=="archived") {
delete_dbWeeks($week);
add_log_entry(''.$_SESSION['f_name'].' '.$_SESSION['l_name'].' removed the week of get_id().'&edit=true\">'.$week->get_name().'.');
echo "Week \"".$week->get_name()."\" removed.
Back";
}
else echo "
Week \"".$week->get_name()."\" is published, so it cannot be removed.
Back";
}
This code tries to do three different actions in one function. The easiest fix is to separate these actions into their own functions. The goal is to have high cohesion.
Too Few Comments: Having looked through most of the code, it is safe for me to say that this software has too few comments overall. Some files, such as personEdit.php, have a decent number of comments. The comments do a good job explaining "why" instead of "how" something is done. A pair of fresh eyes can look at personEdit.php and get a sense of what is happening and why is it important. In my Operating Systems class, students are encouraged to comment all but the most obvious lines of code. An instance variable "counter," when used with a loop, is obviously a counter. Commenting every line would classify as too many comments, and this is also a "bad smell." personEdit.php finds a point in the middle of both extremes.
Other files, such as editMasterSchedule.php, only have a few comments for hundreds of lines of code. Maintenance accounts for a large percentage of a software's life cycle; therefore, good documentation is necessary in order to reduce maintenance costs and avoid future hassles. The function get_day_names() in editMasterSchedule.php is a simple example of too few comments. Monday through Friday are determined through a very similar process via if statements, but Saturday introduces a substring method that is not used for any other day of the week. Why? If there is something intrinsically different about Saturday that requires it to be handled differently than a weekday, a comment should reflect that. Given a few months, it is difficult to forget even your own code. Comments increase readability and reduce maintenance costs. It might take a few extra seconds to type a comment, but the benefits are well worth this extra coding time.
Data Clumps: A data clump occurs when several variables consistently appear together. The only data clump that I can find in this code is related to the date. Month, day, and year are kept together in a date object, but the string name and three character abbreviation are also used to identify days. The function get_day_names in editMasterSchedule.php assigns these string identifiers manually, but this could easily be done in a custom date object.
Speculative Generality: Speculative generality is defined as "inserting features into the code for functionality that is not part of the current requirements." Having looked over chapter 5, appendix A, and RMH Homebase's source code, I have not noticed any included features that are not part of the requirements.
Thursday, February 16, 2012
Day Fifteen: Software Architecture
Chapter 4 in our textbook, Software Development An Open Source Approach, reintroduces many themes and ideas that were previously mentioned in several earlier computer science courses. The recurrence of this information suggests that it is vital to good software engineering practices. For this blog post, I will provide a brief outline of chapter 4, mainly for my benefit, but also for the benefit of others.
4.1 Architectural Patterns
4.1 Architectural Patterns
- Multi-Tier pattern: "GUI components are isolated within the user interface layer and database interactions are isolated within the database layer."
- Client-Server pattern: "separates the functionality of a typical user of the system from that of the server that hosts the database that all users access."
- Transaction Processing pattern: "useful for systems that accept a stream of transactions and process each transaction fully before moving on to the next." ex. ATM
- Model-View-Controller (MVC) pattern: "separate the functionality (the model) that underlies the user interface form the code that controls how the user sees (the view) and interacts with (the controller) the system."
4.2 Layers, Cohesion, and Coupling
- The Layering Principle: "each component appears in a single layer; the user sits at the top layer and the database is at the bottom layer."
- "allows developers to visualize the system as a small umber of interconnected vertical layers."
- The Maximum Cohesion Principle: "All the functions that relate to a single concept are gathered into a single module or class. A software architecture is maximally cohesive if all its modules and classes are cohesive in this way."
- The Minimum Coupling Principle: "Two modules are coupled if either one shares information or receives services directly from the other. A software system is minimally coupled when the number of interaction between all pairs of modules is kept to a minimum."
4.3 Security
- "The first step in ensuring security is to understand the client's requirement that the new software protect confidential and other sensitive information form unauthorized access. A software security policy must be defined for the new system that implements that requirement, and the software must incorporate that policy in a transparent and verifiable way."
4.3.1 Architectural Vulnerabilities
- "Common types of software flaws that lead to vulnerabilities include:"
- "Memory safety violations, such as buffer overflows and dangling pointers"
- "Input validation errors, such as format string bugs, SQL injection, code injection, e-mail injection, directory traversal, cross-site scripting in Web applications, HTTP header injection, and HTTP response splitting."
- "Race conditions, such as time-of-check-to-time-of-use bugs and symlink races"
- "Privilege-confusion bugs, such as cross-site request forgery in Web applications, clickjacking, and FTP bounce attack"
- "Privilege escalation"
- "User interface failures, such as user conditioning, blaming the victim, and race conditions"
4.3.2 User-Level Security
- "When reviewing the security aspects of a software system, we need to ensure that the system enforces the following constraints on users:"
- "Each authenticated user has a unique login id and password, and access to all system functions is provided only after the person enters his/her id and password
- "Each authenticated user has access to only those system functions that are appropriate for their level of access, and no others."
- "Each visitor to the system has access only to those system functions that are appropriate for the general public to access."
4.4 Concurrency, Race Conditions, and Deadlocks
- Many synchronization problems can be avoided with a technique called "locking"
- Locking: "Any session accessing a resource (table or row) in a database gains exclusive control of (a "lock" on) that resource throughout the time required to complete that access (read, write, or update). If a second session tries to access the same resource while the first session has a lock on it, the second session's request is put into a queue until the lock is released. All requests for access to the same resource are handled in a first-come-first-served order."
Subscribe to:
Posts (Atom)