19:13 UTC

add comment

Making it Easier to Announce New Software
by Doc O'Leary, in Editorials - Sat, Nov 11th 2000 23:59 UTC

When you want to announce changes in your project to several Web sites, you go to the first one and fill in a form with your new info. Then you go to the next one and do it again. And again with the next one. And again. And again. Doc O'Leary thinks he has a solution. Please read to the bottom for my comments and a couple of questions I'd like to ask everyone.

Copyright notice: All reader-contributed material on freshmeat.net is the property and responsibility of its author; for reprint rights, please contact the author directly.

Introduction

In the (good ol') days when FTP and archie were king, it was fairly simple for developers to spread their offerings far and wide. I had scripts set up to drop the right files in the right locations, and it didn't much matter if there were two or twenty archives.

Enter the Web, and the focus shifts from pushing software out to archives in favor of pulling people into Web sites. I think that's a good thing, because it puts more information into the users' hands, but in the process, developers have lost the ability to easily push anything out. Instead, we have to manually go to a number of tracking sites (the more the better, usually), set up accounts, and edit essentially the same information on all those sites.

My long-winded question is essentially this: Is there any interest in automating this process? I currently have a property list (easily made available in plist or XML format (and simple to convert to other formats, if necessary)) I can use to build the dynamic pages of my site which contains all or nearly all the information that is gathered at various software tracking sites. If a general software description file format can be agreed on, simply making that file available would give sites all the information they need to update their database entries. No fuss, no muss. Minimizing the administrative efforts will really lower the barrier of entry for all sites.

Reference Files

BetterConsole is my newest piece of software, recently released, which has brought this issue to the surface. You can find my SPIF files for it in two formats:

ASCII plist
XML plist

The plist format might not be particularly easy to parse on non-NeXT/Apple systems, so I would be willing to write a converter that puts out a format that is easier to parse.

Discussion of SPIF format

Keep in mind that this is a work in progress and represents only a first pass effort at a format that contains sufficient information to satisfy most tracking software. Most tracking sites seem to consider a basic piece of software to have eight attributes: author, description, version, system, license, price, category, and package.

author

The author attribute identifies who owns the software. It does this via contact information by assigning values to the sub-attributes name (e.g., Joe Programmer) and location (e.g., http://www.someisp.com/~joe). Other sub-attributes such as email could also be added, though most tracking sites currently only seem to ask for the name and URL of the author.

description

The description attribute identifies the software in increasing levels of detail. Currently that is done with 3 sub-attributes: name, short, and long.

version

The version attribute identifies the version of the packaged software. This is done with 2 sub-attributes: revision, and status.

system

The system attribute identifies what operating systems the software is for. This is done with 2 sub-attributes: name, and version. It may be a good idea to make this an array instead, as some software may run on many different systems (the workaround would be to make a SPIF file for each system). It may also be a good idea to add further system requirements (RAM, HD, etc.), but that does not seem to be a major consideration from a tracking point of view.

license

The license attribute identifies the license the software is distributed under. This is done with 2 sub-attributes: name, and location.

purchase

The purchase attribute gives information on purchasing the software. This is done with 2 sub-attributes: price, and location.

package

Leaving the most complicated for last, the package attribute identifies all the files that are associated with this software. Example sub-attributes are info, binary, and source. Each of these identifies a document that is related to this particular piece of software. That is done by further breaking that file information down to location, size, and checksum. I also included contact information, just in case the contact for, say, the binary might be different from the contact for the source, but I'm not sure that's really necessary.

[You can watch the original version of this document at http://www.subsume.com/spif/ for updates about the file format proposal. -- Ed.]

Editor's Comments

Doc makes a good point -- hackers who would rather be coding have to take the time to submit announcements about their work both to general announcement locations (like freshmeat and comp.os.linux.announce) and to locations that match their specific area of interest (gtk.org or linuxgames.com). This is redundant and time-consuming work, and it would be good to reduce it as much as possible. The question is, how?

A pull proposal

As Doc points out, there are two ways of getting your information through -- you can push it, or you can let people pull it. His proposal for letting sites pull the information from you makes it possible that you would only need to keep one piece of information up-to-date at all the sites on which you want your project listed -- the URL of your project info file. If you want your site listed on freshmeat, gnu.org, and kde.org, you could just give them the URL, and, at a regular interval, each site would have a bot check if the file has changed. If it has, it would compare the file with the information in the site's database and submit any differences as change requests to be reviewed by the site's staff. If the regular interval is taking too long, you could click a button on the site to ask it to check your info file immediately. You could even have an "info file URL" field in the info file, and you wouldn't have to go to the sites to keep the URL up-to-date. When you changed servers, you would put your files up at the new location and change the field in the file at the old location. The URL to the new info file would be submitted as a change request like any other. After allowing enough time for everyone to catch up, you could just remove the old files.

One big thing missing from his first draft is an "announcement" field. When you release a new version, you want it to show up on freshmeat's front page. Using Doc's scheme, you should simply be able to change the necessary fields in your info file, including one that lists what's new in this version, ready to appear in an announcement on freshmeat's front page, in the newsletter, on the newsgroups, etc.

This brings us to a problem I see in doing this. Ask any of the freshmeat staff, and they'll tell you that the number of items that are submitted and approved without any changes is quite small. Sometimes, there are errors in spelling and grammar. Sometimes, it's not clear what the contributor is trying to say, and we have to work it out with him or her. Sometimes, there are just changes that have to be made to make the submission match our editorial policies -- for example, we don't allow the name of the project to appear in the short description, and we insist that it appear in the long description (preferably in the first few words), we don't allow HTML in descriptions, etc.

Now, let's say you make changes to your info file, and we pick them up as change requests. What do we do?

Option one:

We make the changes we need to make, and approve the submission. Unfortunately, your info file still contains the original version; in a few hours, our bot will notice the difference and submit your version again. This will quickly drive us insane.

Option two:

We write to you and ask you to change your info file. This will either:

Delay your announcement unreasonably (you'll wake up the next morning and realize your announcement never went up because we sent you a message pointing out that you spelled Linux with a small "l"), or
Make us lower our standards, and let lots of misspellings through rather than make people wait. (<== Not going to happen.)

Even when we get past that point and your info file is acceptable to us, you'll check your mail in an hour and see messages from two other sites saying that they need you to change x and y. When you change x, site number 3 will be unhappy, and when you change y, site number 1 will be unhappy. At this point, you'll wish you were just going to Web pages and filling out forms again.

The issues of what options to include in the file format can be overcome. Everyone who wants to take part in the system can get together and flame each other until they work it out. Dealing with policy issues and the editorial needs of all the sites is not as easy.

You might end up having tag attributes to accommodate different sites:

<announcement site="freshmeat.net">
    (text acceptable to freshmeat.)
</announcement>
<announcement site="linuxdoc.org">
    (text acceptable to the LDP.)
</announcement>

, etc. Whatever the solution, the problem would have to be dealt with. One size is not going to fit all.

A push proposal

Another idea that comes up from time to time is that of letting people submit information by email. Again, you would have a standard format for the information, only now it would be sent to the sites, where a script would parse it and submit the parts of it as change requests as needed.

The advantage to this is that you no longer have multiple sites trying to get you to change your info file to match their needs. They each receive your request and can contact you with any problems they have. You could have your XML info file in your build directory and have a rule in your makefile with a list of the addresses to which it should be sent and a command that will send it. Then:

make submit

I like that just for the coolness factor. :)

Your proposals

I have two questions for everyone:

Think about the fields currently available for a freshmeat appindex entry and those available in Doc's proposal, in LSM files, etc. Do they provide space for all the information you need to give your audience about your project? What needs to be added or changed?
What suggestions do you have for how your information could be more easily pushed or pulled to all the places you want to keep it up-to-date?

Doc O'Leary (droleary@subsume.com) is a COG in the machine of Subsume Technologies, Inc. (http://www.subsume.com/). He is lazy, and has thus been an advocate of free software since 1996 and of object-oriented development for nearly a decade.

T-Shirts and Fame!

We're eager to find people interested in writing editorials on software-related topics. We're flexible on length, style, and topic, so long as you know what you're talking about and back up your opinions with facts. Anyone who writes an editorial gets a freshmeat t-shirt from ThinkGeek in addition to 15 minutes of fame. If you think you'd like to try your hand at it, let jeff.covey@freshmeat.net know what you'd like to write about.

[Comments are disabled]

Comments

[»] NO ! NO POLLING !! This is better IMHO ...
by GothWolf - Nov 14th 2000 15:38:13

Polling is of course an evil thing!

A =MUCH= better idea IMHO, is that when you have a release, you take your description file and email it to the sites. Each announcement site would have an email account that just grok'd the file and updated the database. Then the authors only have to add the sites to an email list/group and send it out to all of em at once. This would stop silly polling while allowing the author to send out changes with a simple file-attach.

Also, to make sure we don't fake emails, I think a GPG/PGP signature would be called for. I know some people are gonna fuss if required, but I really think authenticated/signed email is gonna become a necessity anyway, might as well get used to it.

Those that don't like signatures would probably have to go to the site and manually log-in and then upload the description file, still a bit faster than going all over. It would also be nice if some of the major sites allowed the others to request the description files from their database by date and/or type or allow remote SQL searches.

I do like the idea of a standard format description file, and I do like the idea of adding dependency information up front. In fact, when browsing freshmeat, you should be able to click the dependency so you know where to get it if you don't have it.

Anyone else hate downloading something, finding out you need another file, and then going back on the net to find it. Then you download it compile it, install it, go back to what you were trying the first place, and then find another dependancy you need ... ARGH!