Blog Fiasco

February 13, 2013

How do you measure software quality?

Filed under: Linux — Tags: , , , , — bcotton @ 10:30 am

There are two major license types in the free/open source software world: copyleft (e.g. GPL) and permissive (e.g. BSD). Because of the different legal ramifications of the licenses, it’s possible to make theoretical arguments that either license would tend to produce higher quality software. For my master’s thesis, I would like to investigate the quality of projects licensed under these paradigms, and whether there’s a significant difference. In order to do this, I’ll need some objective mechanism for measuring some aspect(s) of software quality. This is where you come in: if you have any suggestions for measures to use, or tools to get these measures, please let me know. It will have to be language-independent and preferably not rely on bug reports or other similar data. Operating on source would be preferable, but I have no objections to building binaries if I have to.

The end goal (apart from graduating) is to provide guidance for license selection in open source projects when philosophical considerations are not a concern. I have no intention or desire to turn this into a philosophical debate on the merits of different license types.

January 15, 2013

Deploying Fedora 18 documentation: learning git the hard way

Filed under: Linux,The Internet — Tags: , , , , — bcotton @ 5:49 pm

If you haven’t heard, the Fedora team released Fedora 18 today. It’s the culmination of many months of effort, and some very frustrating schedule delays. I’m sure everyone was relieve to push it out the door, even as some contributors worked to make sure the mirrors were stable and update translations. I remembered that I had forgotten to push the Fedora 18 versions of the Live Images Guide and the Burning ISOs Guide, so I quickly did that. Then I noticed that several of the documents that were on the site earlier weren’t anymore. Crap.

Here’s how the Fedora Documentation site works: contributors write guides in DocBook XML, build them with a tool called publican, and then check the built documents into a git repository. Once an hour, the web server clones the git repo to update the content on the site. Looking through the commits, it seemed like a few hours prior, someone had published a document without updating their local copy of the web repo first, which blew away previously-published Fedora 18 docs.

The fix seemed simple enough: I’d just revert to a few commits prior and then we could re-publish the most recent updates. So I git a `git reset –hard` and then tried to push. It was suggested that a –force might help, so I did. That’s when I learned that this basically sends the local git repo to the remote as if the remote were empty (someone who understands git better would undoubtedly correct this explanation), which makes sense. For many repos, this probably isn’t too big a deal. For the Docs web repo, which contains many images, PDFs, epubs, etc. and is roughly 8 GB on disk, this can be a slow process. On a residential cable internet connection which throttles uploads to about 250 KiB/s after the first minute, it’s a very slow process.

I sent a note to the docs mailing list letting people know I was cleaning up the repo and that they shouldn’t push any docs to the web. After an hour or so, the push finally finished. It was…a failure? Someone hadn’t seen my email and pushed a new guide shortly after I had started the push-of-doom. Fortunately I discovered the git revert command in the meantime. revert, instead of pretending like the past never happened, makes diffs to back out the commit(s). After reverting four commits and pushing, we were back to where we were when life was happy. It was simple to re-publish the docs after that, and a reminder was sent to the group to ensure the repo is up-to-date before pushing.

The final result is that some documents were unavailable for a few hours. The good news is that I learned a little bit more about git today. The better news is that this should serve as additional motivation to move to Publican 3, which will allow us to publish guides via RPMs instead of an unwieldy git repo.

January 11, 2013

A wrinkle with writing your resume in Markdown

Filed under: Linux — Tags: , , , , — bcotton @ 11:59 pm

For Sysadvent 2011, Phil Hollenback wrote an excellent post called “Write Your Resume in Markdown Already!” Ever since I read it, I’ve been using a Markdown file as the source for my resume, which gets rendered to HTML and PDF as necessary. Recently, someone using Windows tried to open the PDF of my resume in Acrobat Reader. When she did, she got errors about missing fonts. “How odd,” I thought. In the course of several job applications over the past year-plus, I hadn’t heard of any problems. (It’s possible that nobody reviewing my resume used a Windows machine to do it.)

I fired up my Windows XP virtual machine that I keep around for playing Sim City 2000 and installed Adobe Reader. I was able to reproduce the problem, which is always comforting. It didn’t shed any light on the matter, though. I actively avoid doing anything “cute” so that my resume (and other documents) can easily be read by anyone on any platform. After examining the workflow, I figured that the problem had to be in the LaTeX template used to generate the PDF.

One of the features of the template is the conditional use of packages and font settings. Since the pandoc package in Fedora 17 (version 1.9.4.2) no longer includes the markdown2pdf command in previous versions, the –xetex argument that Phil passed isn’t necessary. Removing the control structure resulted in a PDF that looked qualitatively the same, but would open on Windows. Phil’s instructions are still good overall, but they need some tweaks for newer versions of Pandoc.

Here’s a diff, for those of you who are interested:
7,9d6
< $if(xetex)$
< \usepackage{ifxetex}
< \ifxetex
15d11
< \else
18,22d13
< \fi
< $else$
< \usepackage[mathletters]{ucs}
< \usepackage[utf8x]{inputenc}
< $endif$

 

October 2, 2012

Proposed change to Fedora docs schedule

Filed under: Linux — Tags: , , , — bcotton @ 7:59 pm

In the most ideal situations, project management can be a challenge. In a fast-moving, community-driven, highly-visible project like Fedora, it can be near-madness. Although the Docs group tries to keep to the schedule when producing guides, the unfortunate reality is that guides rarely meet the scheduled milestones. I’m a firm believer in the idea that if the schedule is never met, it’s the schedule that’s wrong, not the contributors.

With that in mind, it was proposed in this week’s Docs meeting that the branching of guides be 4 weeks prior to the final release date, instead of shortly after the Alpha release. This buys guide writers more time to incorporate the changes a new release brings. Unfortunately, it puts an extra crunch on translators since they then only have four weeks to update translations if guides are to ship in concert with the OS.

The reality is that it doesn’t change much, I expect. Since the reality is that the guides don’t come in on time, it does little harm to have the schedule reflect that fact. I hope. I posted a message to the Docs and Translation teams earlier this week requesting comment. Modified schedule proposals are available at http://bcotton.fedorapeople.org/docs_schedule/.

August 31, 2012

Release Notes beat writers needed!

Filed under: Linux — Tags: , , — bcotton @ 8:33 am

The Release Notes beats for Fedora 18 are open:¬†https://fedoraproject.org/wiki/Category:Documentation_beats. The beats cover specific areas of the next Fedora release and end up directly in the Release Notes that the Docs team produces. This is a great way for new contributors to leave their mark. Since all of the writing is done in the wiki, you don’t need to learn DocBook. All you need is a FAS account to log in to the wiki. So find an unclaimed beat that looks interesting to you and make it yours!

April 25, 2012

Fedora release names

Filed under: Linux,Musings — Tags: , , — bcotton @ 9:25 pm

Last week, the voting for the Fedora 18 release name was opened, along with an announcement that the board is considering whether or not to continue the practice. Undoubtedly, this is a reaction to some of the hand-wringing over naming Fedora 17 “Beefy Miracle.” Yes, Beefy Miracle is a silly name. Yes, it is likely to be forgotten shortly after the release.

My own position is somewhat ambivalent. The naming process is democratic, and represents the Fedora Project as a whole. The fact that names will sometimes be silly or offensive to a cultural group is part of life in a democracy. The naming process provides a little bit of fun near the end of the release cycle when life gets hectic for contributors. Perhaps the most important aspect of the name is that it provides a theme around which artwork and release announcements can be crafted.

On the other hand, if the release names go away, I can’t say that I’d really care. Release names tend to be forgettable for most distributions (Ubuntu and Debian releases are the ones I’ve ever heard people refer to by name in conversation), and I don’t think it would be any loss to the Fedora community or product if naming went away. To be honest, I’ve already forgotten how I voted in that poll. Whatever the community decides is fine, so long as we continue to remain a community.

December 24, 2011

Fedora Docs QA

Filed under: Linux — Tags: , , — bcotton @ 11:43 pm

The Fedora Documentation team has been kicking around the idea of adding a QA process for a while. The idea is to catch errors in formatting, spelling, and grammar before a guide ships. The challenge is that all of our manpower is volunteer. They have jobs and lives, and don’t always have the time to do extra steps, even when those are needed. This problem exists for all community-driven projects, but it’s my first time experiencing it in a leadership position.

Fortunately, there are some great contributors. I think the QA process we developed will work really well. The main challenge will be doing QA-by-committee, which will require me to be a nagbot when tickets go stale. I will rely heavily on the bugzilla command line tool to nag me to nag the QA group. After Fedora 17 is released, we’ll revisit our process and see what needs to be fixed.

November 8, 2011

Fedora 16 released

Filed under: Linux — Tags: , , , — bcotton @ 10:03 am

It’s that time again — a new release of Fedora is here! I’m about to eat my own dog food and upgrade, so while I do that, why don’t you check out the Release Announcement? This release announcement holds a special place in my heart because I mostly wrote it (along with contributions from others, of course!). That’s right, I’ve actually made a contribution. It sets a dangerous precedent, but I found writing the RA quite enjoyable. I’m particularly proud of my Jules Verne references in each of the “What’s New” subsections. Fortunately, we’ve got a little while to come up with “Beefy Miracle”-themed one liners.

So even though I haven’t yet installed it, I’m confident that Fedora 16 is just as great as the last 15 versions. I’ll have some notes about the upgrade process once it finishes.

November 1, 2011

How should we deliver documentation to users?

Filed under: Linux — Tags: , , — bcotton @ 6:44 am

Dear Fedora Diary,

I’ve noticed that many people on Fedora Planet are posting daily-ish activity logs. I don’t contribute on a daily basis, so uninterested readers won’t have to put up with too much, but it seems like a reasonable thing to do. In the future, I’ll call it “Fedora Diary”, but today there are actual things to discuss.

It all started at 9 AM yesterday when I showed up in IRC for the Docs meeting. None of the usual leaders-of-meeting were around, so I took initiative and ran the meeting. I’d done this once before, so I didn’t screw up too badly. I’d say I need more practice, but I don’t want anyone to get any ideas.

At the end of the meeting, Pete made a comment about how cluttered the wiki is. His point is valid. With end user documentation mixed in with¬† internal minutes, agendas, etc., it can be challenging to find the right page. Even with a good search term, it’s not always evident which page is the right page, and that can frustrate users who just want to find the relevant nugget to fix their immediate problem.

Petr suggested that all user-intended documentation should be in the guides produced by the Docs team. I understand the sentiment, but I’m not sure it works. Certainly there’s a place for user documentation on a wiki, even if it gets reproduced in a guide. The real issue is that guides and wikis are different tools, and have different purposes. I’m not sure that there’s an advantage to exclusivity in medium.

This brings me to what I consider the more interesting question. How do users get the most benefit from documentation? I don’t know what sort of research (if any) exists on the subject, but it seems like something that should get figured out. Perhaps that’s a reasonable direction for my M.S. thesis?

October 11, 2011

Fedora 17 is a [Beefy] Miracle

Filed under: Linux — Tags: , — bcotton @ 9:14 pm

There’s been a lot of noise on Fedoraplanet and social media about the name that the community has chosen for Fedora 17. If you haven’t yet heard, the election results are in and the winner is “Beefy Miracle”. If you’re not familiar with the naming process for Fedora releases, it goes something like this: community members submit candidate names that are related ($name is a ___, as is $name-1) but not in the same way that $name-1 and $name-2 are related. Names are checked for collisions, conformity to the rules, and legality. Community members then vote on it. It’s a very open process, as you would expect from the Fedora Project.

Clearly, the community has spoken. Yes, it is a silly name. But it’s no sillier than Slutty Salamander or whatever the latest Adjective Animal from Ubuntu is. And let’s face it, there have been some less-than-awesome names in the previous 16 Fedora releases. Opponents of the name (and there are many, from what I can tell) can take solace in the fact that they’ll no longer have to hear anyone lobby for it. And the rest of us will just have to get to work trying to figure out what names to suggest for Fedora 18.

Older Posts »

Powered by WordPress