User:ADalal

From TeachingOpenSource

Bio

Amy Csizmar Dalal is an Associate Professor of Computer Science at Carleton College in Northfield, MN. She teaches courses at the introductory level, as well as Data Structures, Software Design, Computer Organization and Architecture, Human-Computer Interaction, Computer Networks, and Computer Security. She also regularly supervises senior capstone projects and is very involved in integrating academic civic engagement into her courses. Her research interests include quality of service/quality of experience of Internet applications; self-healing networks; human-computer interaction; streaming media; network measurement; and performance analysis of computer and communication networks.

In her spare time, Amy is an avid runner and voracious reader and likes to spend as much time as possible outdoors.

Email: adalal@carleton.edu
Twitter: @drcsiz
Website: http://cs.carleton.edu/faculty/adalal
Blog: http://acdalal.wordpress.com

Part A Activities

Project Anatomy Activity notes

Sugar labs project

  • The most natural roles for my students would probably be developer, designer (for HCI classes and/or capstone projects), and content writer (technical content).
  • It looks like you submit bugs through the repository, and then I assume they are auto-added to the bugtracker. I found it interesting that most of the bugs I clicked on when poking around the bugtracker were many years old --- kind of a scary thought! I wish there was a way to sort by date added so it's easier to see the newer bugs. Also, the process for submitting a bug does not seem to be very user-friendly --- the issues page doesn't provide a lot of info on what data the developers would like to know, and the "how to submit a bug report" guide was long, rambly, and at times condescending.
  • Last commit was 3/10/2014 (?!) according to the Activity page
  • The roadmap is updated at the beginning of each release cycle

Sahana Eden project

  • There are definitely distinct roles in this project. This project also had a much different "feel" than Sugar Labs. Whereas the Sugar Labs page seemed a bit more hierarchical ("contact this person if you want to contribute as an X"), these pages seem more to invite the person to jump in and start playing around with things. I also found the information on submitting bugs under the Testing page to be WAY more accessible and useful than the one for the Sugar Labs project. In summary, Sugar Labs felt like you had to join an exclusive club to contribute, while Sahana seems more open.
  • The bugtracking page is way better organized and easier to follow than the one for Sugar Labs. You can actually see dates and things are better categorized.
  • Roadmap: again, the info here seems well-organized, with succinct summaries of deliverables or work-in-progress. Seems like no recent activity, though, so it's unclear when/how often these are updated.

Summary: It was interesting to see how differently each project presented itself. It's made me think that one of the important factors in deciding on a project for a class should be how welcoming the community seems. I could see how, for instance, someone who maybe is not as sure of themselves as a CS major could feel overwhelmed or put off by the way a project is presented, and how this could actually turn someone off from CS, rather than attracting them to CS.

Part B Activities

FOSS Field Trip

See blog post

Project Evaluation

Project under consideration: OpenMRS (which is also the project I'm currently considering for my classes).

Viability criteria

  • Based on the data from OpenHub and the OpenMRS page, I would rate this project 3 (high) on the size/scale/complexity scale.
  • Based on the number of commits from looking at the repository and from the OpenHub stats, I would say OpenMRS is definitely active. There have been commits in the last several months and new developers have joined and committed code in the last several months.
  • It seems from the IRC logs, Talk activity, and downloads that this project has an active community. The IRC logs indicate that people can easily get help in real time (there seems to be activity over most hours of the day); similarly, there are active discussion threads on Talk. I'm guessing from the stats that there was a major release in August of this year given that downloads went up by a factor of 2-3 (and are now back down by a factor of 3).

Approachability criteria

This project gets a B+/A- for approachability. There is an extensive set of developer guides that seem to be fairly well written (from my quick skim), and seem to make it way less scary to start contributing code. Contributing in the testing and documentation areas are somewhat well-documented. However, I wonder if "contact the developers' email list" as one of the first instructions for getting involved as a tester is off-putting to some people. Similarly, the documentation for the documentation area lists areas where documentation is needed, but it's less clear if this is up to date and who is "in charge" of curating this content.

That said, this project appears to have thought carefully about how to attract potential contributors and make them feel welcome, which is very refreshing and professional.

Suitability

  • There seems to be good, clear documentation about how to "claim" a ticket and resolve an issue. I also noticed a lot of the introductory issues have a good deal of discussion about the best way to approach the problem, and some already have unit tests. This would definitely decrease the learning curve for my students. That said, I could see wanting to do an in-class lab activity to help my students get everything set up and ready to go before they tackle one of the issues.
  • As I mentioned in the previous section, IRC and Talk activity indicate that questions are usually answered in a timely manner, and the documentation for developers seems to have taken into account most questions new users would have about getting started. I would rate newcomer support highly.

Summary

After reviewing this project, I think it would be a good fit for a Comps project (our version of the senior capstone course). Our students work in teams over 2 academic terms, so there would be enough time to get up and running (install the environment, claim and resolve some issues, submit patches and unit tests) and also make non-trivial contributions to the project. I could see the value in identifying one or more key "contacts" that my students would interface with to make things easier, but I suppose I'd have to negotiate this beforehand.

FOSS in Courses, Part 1

I went into this workshop thinking that I would use FOSS as part of our senior capstone experience ("Comps" at my institution). I'm still thinking that way, primarily. However, the readings for this activity have me thinking instead about how I could revamp some of my in-class activities in Software Design (a course required for our majors that's partly software engineering, partly object-oriented development, partly a dumping ground for things we think our majors should know about software development that aren't covered elsewhere). So I'm going to focus on that class for my learning activities for this exercise.

In the section of the course that covers code design and the art of writing programs, I have two go-to in-class activities. In one activity, the students classify comments according to the "taxonomy" in Code Complete. In another, they refactor/restructure some code, usually a method or a set of methods, for style and clarity. In both cases, I've had students bring in their own code for the activities, and have them work through each others' code in groups. This works well enough, but the downside is that they are already familiar with the code (even if they wrote it back in Intro CS). I've thought in passing in the past that having them look at unfamiliar code would be more effective for this exercise.

Let's drill down into the first activity. I found this activity in the list of learning activities useful. This is how I'd modify it to work in my Software Design course as a one day in class activity.

  • Readings: I've assigned the chapter on comments from Code Complete in the past, and I think the reading serves as an important point for starting discussion. My students have a love/hate relationship with this reading, but that's ok. Give students a reading quiz before class to make sure they've done the readings beforehand and come in ready to work.
  • Leading discussion: I envision that these in-class activities will be taken from the same FOSS project over the course of the term, so the students should already be familiar with the project. This means we'll have time to review McConnell's points and come up with our own class "rubric" for evaluating comments in the project code. (Include a brief discussion of style, too, which I'm not sure if McConnell covers.)
  • Workshop: Students are in groups for this. (Ideally, I'm teaching in the "sandbox" room where I normally teach, where students are at tables w/ their own whiteboards and monitor per table.) Each group gets some already commented or partially commented code from the FOSS project. (Give the same code to 2 different groups, so we can compare/contrast the groups' assessment during report-out time.) The group applies the rubric to the code, assigns it a final "grade", and then makes suggestions to improve the comments.
  • Report out: Groups summarize their findings and the top 2-3 comment changes they would make. Compare and contrast evaluations from groups on the same code snippet.
  • Homework/practice: part of each project grade for the 2 major course projects will be for effectiveness of comments, using the criteria selected by the class in this exercise. Also, when we do code reviews later in the term for the 2nd project, comments will be a component of the discussion, again using the class' rubric.

Part C Activities

Bug Tracker Activity

Bug tracker columns summary
Column Meaning
ID Number identifying the issue in the DB
Sev Severity of the issue. Possible values (by decreasing severity): Blocker, Critical, Major, Normal, Minor, Trivial, Enhancement. source
Pri Indicates how quickly this issue should be addressed. Possible values (by decreasing priority): immediate, highest, high, normal, low, lowest. source
OS Operating system for this issue (i.e. for a bug, the OS you were running when you identified the bug)
Product This is the specific part of the software (package, tool, etc) which has the bug
Status Where the bug stands now. Possible values: Unconfirmed, New, Assigned, Reopened, Needinfo, Resolved, Verified. source
Resolution This applies only to closed issues, and indicates why the issue is closed. Possible values: Fixed, Invalid, Wontfix, Duplicate, Worksforme, Incomplete. source
Summary Very short description of the issue

Bugs appeared to be displayed initially as: all open ones first, with the ones that need more info on the top, followed by reopened, assigned, new, and unconfirmed.

Shading/colors: Light grey appears to indicate enhancement requests. Red seems to indicate a critical issue. Boldface indicates a blocker issue? Black for everything else.

Drilling down into two bugs:

  1. Bug 460668: The issue is that the software does not "remember" a column's resizing. There was some discussion/pleading for a fix in January 2016, and an additional plea for a fix in August, but it does not look like a fix has occurred (although one of the commenters helpfully pointed towards some likely methods that could be called to fix the problem). The bug is assigned to "RhythmBox Maintainers". To fix this, I'd probably start with the method calls identified by the commenter, perhaps testing them in a smaller proof-of-concept interface first to ensure that the behavior is what I want. I'd then integrate that into the existing code (after obtaining the latest branch) and test before submitting a patch.
  2. Bug 648260: The issue is that the documentation for several of the states is unclear and/or wrong and/or misleading to developers. The most recent discussion was in Dec 2013/Jan 2014, but it does not look like the bug has been resolved. The bug is assigned to "ATK maintainer(s)". To fix this, I'd read through the discussion more closely to figure out exactly where the points of confusion lie. I'd then go into the code and look at the states in question, both the implementation and the usage, and write some simple test code to exercise this code and get a better sense of its behavior. Once I've done all of these things, I'd write up new documentation in the form of comments and submit as a patch. (Actually I'd probably post to the bug tracker first, to make sure my thinking is in line with the developers'.)

Collective reports:

  • 283 bug reports were opened and 245 were closed last week. I'd call that about even.
  • The top 3 bug closers were Sebastian Dröge, Michael Natterer, and Milan Crha. These people are likely in charge of some portion of the project.
  • The top 3 bug reporters were Mohammed Sadiq and vrishab (tie), and Christian Stadelmann and Sebastian Dröge (tie). The first two reported 3 times as many bugs as the next 2. There was exactly one overlap on the list of top 15 bug closers and reporters (Sebastian).
  • The top 3 patch contributors were Philip Chimento, Carlos Garnacho, and Ting-Wei Lan. Philip and Ting-Wei were also on the top 15 bug reporters list, and Carlos was on the top 15 bug closers list.
  • The top 3 patch reviewers were Sebastian Dröge, Florian Müllner, and Cosimo Cecchi. Sebastian reviewed more than twice as many patches as Florian. Florian also appeared on the top 15 bug reporter list. There is some overlap between the patch reviewer and the bug closer list, which makes sense.
  • Most of the braille bugs were of normal severity. NOTE: I found the stacked bar graph much easier to read than the bar graph here.
  • You can make a line, bar, or pie chart (or list the results as a table). You can slice and dice the fields/filter the data in various ways.

FOSS in Courses, Part 2

The following is a revised/more fleshed out lesson plan for the effective commenting in-class activity I described in FOSS in Courses, Part 1.

Activity: Comment classification

Type of activity

In-class, 1 to 1.5 class periods.

Learning objectives
  1. Students will be able to classify comments using McConnell's criteria
  2. Students will be able to evaluate the effectiveness of various types of program comments in aiding code understanding.
  3. Students will be able to explain and reason about the role of comments in code documentation
  4. Students will be able to apply this reasoning to their own code comments, critically evaluating their own comments and incorporating more effective comments into their own code.
Pre-requisites (pre-class homework)
  • Readings: Chapter 32, sections 32.3-32.5, in Code Complete (2nd ed).
  • Complete online pre-class reading quiz about the concepts in the readings

Note: The students will already be familiar with the code in question, as we've studied it throughout the term. Prior to this, students will have examined a portion of the FOSS code, evaluating it for its code structure (classes, methods, variable names, level of cohesion, etc). This activity would work with the same portion of the code as these previous activities.

Course timing

This activity would occur about 3-4 weeks into a 10-week term. It would require several hours of instructor prep, to create the online quiz, review and pre-classify the relevant code, and design the rubric form and discussion questions.

The nice thing about this activity is that it can be accomplished out of sync with the FOSS project. There is a possibility that students could contribute modified code back to the project --- this would require some discussion between me and the FOSS team beforehand. If there is community documentation about code style, I would require my students to read this (if we haven't done so already) beforehand.

Description of activity

Note: I usually teach this class in a collaborative classroom with tables and whiteboards on all the walls. This means my students are already divided into small groups. When I say "tables", I mean "small groups".

The in-class activity would consist of the following steps:

  • Review of readings: As a class, summarize McConnell's main classification points, and give examples of a type of comment that fits that classification. (Ask for student contributions and/or have each table recall the points, list them, and come up w/ an example of one of them.) Time: 5-10 minutes.
  • Rubric creation: Whole-class/table discussions. Time: 20 minutes.
    • Whole class: Recall and list the FOSS community standards for this project around comment style, content, etc. (assuming such standards exist and are outlined somewhere!)
    • Tables: Are there any other standards that we should consider, about style or substance, that are not covered in the community standards or in McConnell? List them now. (report out to class if there are any additions)
    • Tables: Weight each of the criteria from all three sources (grouping similar criteria). What categories emerge?
    • Whole class: Come to consensus about the main categories.
    • Tables: Give each table a category and have them come up with a rubric to evaluate that category.
    • Whole class: Combine the categories into a single rubric. Discuss points of contention. Finalize rubric.
  • Comment workshop: Each table gets some already commented or partially commented code from the FOSS project. (Give the same code to 2 different tables, so we can compare/contrast the tables' assessment during report-out time.) The table applies the rubric to the code, assigns it a final "grade", and then makes suggestions to improve the comments. Each table then reports out, and we discuss points of contention/disagreements. Time: 25 minutes.
  • Comment fix: (optional) If we do decide to contribute code back to the community, have each table make modifications to the code comments, then submit a bug fix/pull request. (Note: may require coordination among tables if the fix covers the same code.)
Assessment

Since this is an in-class activity, there is no formal assessment, other than agreement/consensus/feedback from classmates (and me!) during the activity and during the reporting out and discussions.

If we do contribute code back to the project with modified comments, the FOSS community will "assess" this work by deciding to accept or reject the fixes. Note: there is a chance that this could be a mini-project, with the students fixing not just comments but code structure (method structure, variable names, etc) more generally. The latter is the topic that immediately precedes the topic of self-documenting code.

There will be indirect assessment resulting from this activity. I will use a version of the comment rubric that the students develop in evaluating comment structure on the two major projects in the course.

Concerns and barriers

There is always the possibility that this is not help the project wants or needs. Judicious choice of project can help here.

The comment rubric will also be used later in the course, as part of the in-class code reviews.