Opera Nalakuvara, customized Taiwanese browser — Part 4: Deployment, documentation, testing

By Jedi Lin

Introduction

Nalakuvara is now almost complete. With the main coding and customization all done, it's time to move in to the endgame, which is what we'll cover in this article. I will show you how to package and deploy Nalakuvara. We will talk about creating useful documentation, and discuss the process of soliciting testing, and dealing with community feedback effectively.

Packaging

The packaging process on each platform is fairly simple. On Windows, I first compile the AutoHotKey scripts into an .exe executive, then pack all necessary files into a RAR SFX archive, which is a good packaging format because you can set it to launch a specific file upon extraction. You could consider using NSIS too — it handles multiple languages better, but it is harder to extract and less commonly supported.

On Linux/FreeBSD, packaging is even simpler — I just make tarballs for the different platforms: tar.bz2 for Ubuntu (deb) and FreeBSD, tar.gz for Fedora (rpm) and tgz for generic Linux.

To help users make sure that their downloads are not corrupted, the file download page also provides a MD5 checksum of each file. MD5 however is a little too geeky. In order to help the average end user, there is a standalone file checker based on the MD5 checksum that is compiled from an AutoHotKey script. It is the one checker to check them all. If the downloaded file belongs to any one of the current releases, it reports the file's detail, otherwise it asks users to download again. By providing this checker, novice users and advanced users can both make sure that their download file is error-free.

Documentation

Documentation is the basis for communication — I spend more time on documentation than coding/scripting. If the importance of documentation isn't obvious, I wouldn't be spending so much time on these articles!

For documentation to be effective, I needed to balance the needs of geeks with those of average end users. User documents help users to understand the whole project, know where to tweak configuration options further if needed, and how to apply changes manually. Geek documents are for geeks, for those who want to know the actual process behind Nalakuvara, and for those who want to do a similar project.

Because Nalakuvara is for Taiwanese users, currently all documents are only in Traditional Chinese. The articles you are reading now constitute the first English Nalakuvara documentation.

User Documents

Nalakuvara documents are updated frequently and available online. Here is a list of the most useful ones to check out:

  • The Nalakuvara main index describes the history of this project, TODOs, and known issues
  • The Nalakuvara feature page introduces the guidelines of Nalakuvara, details all features (with screenshots), and links to add customized buttons
  • The Nalakuvara download page lists all available downloads of current Nalakuvara versions, with some utility files such as a script to enable mouse gesture trail
  • The Change log page records all changes committed since the first release of Nalakuvara. Users who use the Patch Package will be led to the patched result page, which provides information on several of Nalakuvara's tweaked defaults, such as bookmarks and Toolbar buttons. In case Nalakuvara's patch does not work, users still know how to fix them by themselves

All these documents are user-oriented. This means that all information is in plain language, with images, lists and tables to facilitate understanding. With these documents on hand, most users could easily find what they need, and I can easily answer most user questions by providing a single URL.

Geek Documents

Geek documents provide something extra for more technical users of Nalakuvara. The Technical details page is basically like a shorter version of this article series, which explains many things, including how and why I made certain decisions, and how I implement the Nalakuvara customizations.

For the hardcore, the actual documents are within the source of my scripts — all scripts are commented nicely, line-by-line, in Traditional Chinese. There are even more details in those comments than in this article. (Would anyone like to see thousands lines of code in this article? I doubt that.) Studying these scripts, you can learn how to modify not only Opera, but some AutoHotKey modifications as well.

Geek documents help geeks to truly take control of Nalakuvara. I myself am one of their biggest beneficiaries. Even after months or years have passed, I will still be able to tell which line of the codes is doing what at a glance.

Test and Release

Even when all the files have been packaged nicely, and documentation is fairly complete, you can't just throw your software out into the wild — it must be tested first, and you need a decent strategy for release. We will discuss these things in this section.

Test Environment

The first step of testing is to prepare test environments. As mentioned before in the first part of this series, virtual machines help a lot. For the supported platforms (OSes), it is better to take several snapshots to test with. The following are the snapshots I worked with during Nalakuvara testing:

  • Brand new default installation
  • Brand new default installation with all service packs from vendors
  • Brand new customized installation
  • Brand new customized installation with all service packs from vendors
  • Brand new customized installation with all service packs from vendors, and Opera 9.64 installed with default options
  • Brand new customized installation with all service packs from vendors, and Opera 9.64 is installed with customized options
  • Brand new customized installation with all service packs from vendors, and Opera 10.00 is installed with default options
  • Brand new customized installation with all service packs from vendors, and Opera 10.00 is installed with customized options
  • Brand new customized installation with all service packs from vendors, and with a different 3rd party web browser as the system's default web browser
  • Upgrade installation from previous versions

You could add more snapshots to the list above. However, once you identify different instances in which the installation and testing works out exactly the same, you can eliminate them to prevent wasting time.

Testing routes

A "route" is how users complete one process. Let's take Full Installation Package as an example (full installation of Nalakuvara) — there are 249 possible routes! The nightmare begins with 10 test situations on each of 10 different systems, which makes 24,900 routes to test in total. It is quite impossible to fulfill all of them, but at least you should perform all 249 routes in one situation, on one system. Once or twice I was too lazy to do all the tests, and some packages just failed stupidly in certain situations.

Note: To save time, look into doing unit tests. 249 routes could be two units with only 20 routes in total. You could also use debug code to help you, for example:

; debug mode switch
DEBUGMODE = 1

; blah blah blah...
;
; some code here
;
; yada yada yada...

; print debug message only when debug mode is on
if ( DEBUGMODE = "1" ) {
MsgBox, 64, DEBUG MESSAGE, variable foo = %foo%
}

; blah blah blah...
;
; code continues
;
; yada yada yada...

Deployment

After the test phase has proved successful, it is time to make the project release public. Since I am using Perforce as a version control system, I can use that to pull updates to my web server. I set up a crontab:

P4PORT=HOST:PORT
P4USER=USERNAME

45 * * * * /usr/local/bin/p4 sync

This keeps files up-to-date hourly, which is enough for minor changes or routine maintenance. When I am ready to release a new build, I just manually do p4 sync. Please note that by default p4 login gets a ticket that only validates for 43,200 seconds (ie, 12 hours). In order to keep the crontab working, you have to first specify Timeout: unlimited with the p4 group command to create a group of users with issued tickets that never expire.

My web server has another problem too. I host my web server with a 10M/2M ADSL connection, thus it cannot serve more than 2Mbps outgoing bandwidth in total. There are a few ways to balance traffic. Coral Content Distribution Network (CoralCDN) provides a free peer-to-peer content distribution network. Just append .nyud.net to the hostname part of file downloading URLs:

<a href="http://Jedi.org.nyud.net/p4/Opera/pub/Release/Opera-10.00.Nalakuvara-RC2.exe">download</a>

I also use file hosting services such as RapidShare and other mirror sites to provide alternative downloads. Do not forget to provide file checksums (MD5/SHA1/SHA256 or so) to verify files.

Usually I only do these works after a Release version of Opera has been released. By not basing Nalakuvara on Beta/Alpha/Pre-Alpha/Snapshot versions of Opera, I can allow users to focus on real bugs. This helps debugging both Opera and Nalakuvara. However, I do announce brief test reports for certain pre-release test results, so that users can predict what will happen in future releases.

Community

Community is the core value of any software project. It is important to feed information to your community, and use feedback from it effectively.

Feeds

When your project is exposed to the public, thousands of visitors will come to check it out, but the truth is that most visitors come to visit once; only very few will be back again. It means that most people will not pay much attention to any project.

If you want people to keep tab with your project's development, you have to do something. Feeds, for example, are a good method of ensuring this. People might subscribe to your feeds during their one-time visit, and might come back again if you publish something interesting via feeds. There are also many other communication channels, such as Twitter and Plurk, which basically do the same job.

The point here is to create a "laziness-friendly" environment, so that people don't think participation and following updates will be too much work.

Once the channel is set, create some buzz. Every time you find a bug, fix a bug, add a feature or even write a document, let the people who subscribe know about it. Feed your users and they will stay and grow. That is the beginning of the community.

Feedback

The community, however, cannot rely on one-way communication. You have to listen to and talk to the members. Some channels, such as Twitter and Plurk, are capable of two-way conversations. You should use social platforms where users hang out, too. Remember those places when doing background analysis.

I spend lots of time on related forums like Ptt BBS every day. How users use your software might differ considerably from what you first expect. The needs of users evolve from time to time, so should your project. Of course, you still have to keep the basic guidelines in mind.

The fake User Agent string list mentioned in the end of the "Tweak Defaults" section in part 2 is one of the results of community contribution. About a month ago, I started a spreadsheet on Google Docs and Spreadsheets. The priviledge of that spreadsheet is set to public, and everyone is welcome to edit freely. Later I posted this spreadsheet URL at Ptt BBS, and users started to contribute their findings.

It is neither easy nor simple to manage a community. Nalakuvara has a long way to go, and I still have a lot to learn. I am learning a lot from "The Art of Community,", a new book written by Jono Bacon, the Ubuntu Community Manager, and published by O'Reilly. The best part of it is that this book is also released online under a Creative Commons Attribution-NonCommercial-ShareAlike license. Why not get a free PDF download right now?

Conclusion

This concludes your guided tour of the Nalakuvara project! I hope the articles are useful, and might have even inspired you to create your own browser customization project.

There are many different ways to do things. You could do it quick-and-dirty, or make it more drawn out and step-by-step. From a long-term point of view, I believe that a solid path make things much easier. Even readers outside the browser world still benefit from these details. That is why I take time to write documents and articles like this one.

Opera itself evolves, too. One day Opera might reach perfection and cover all features from Nalakuvara. By that time, there will be no need to continue the Nalakuvara project. However, with all these documents, all the contribution and community interaction will not be in vain.

This article is licensed under a Creative Commons Attribution, Non Commercial - Share Alike 2.5 license.

Comments

The forum archive of this article is still available on My Opera.

No new comments accepted.