Skip to content

Simon Josefsson's blog

Menu

Primary menu

  • About

Month: September 2013

BLURB: Software repository metadata convention

Posted on 2013-09-24 by simon — 9 Comments ↓

As a maintainer of several software packages I often find myself copying text snippets from the README file into different places (savannah, github, freecode, emails, etc). Recently I had a need to generate a list of software packages that included every project’s name, brief summary, license and URL. I could have generated that list manually by copying the text from every project’s README and COPYING files. However then I would have to maintain my list manually to keep it in sync with all the projects. This easily leads to stale information, so I thought a better approach would be to put the information I needed into each projects’ source code version control system. The advantage is that the manual work to extract the information may be automated by a script, since the data is in a usable format. I’ll explain here how my solution works.

To be able to find the information using only the URL to the repository, I needed a filename convention. The filename I chose was BLURB; for the etymology, see Wikipedia’s page about Blurb. The data format in the file is similar to normal email headers.

An example illustrate the principles well. Below is the BLURB file for one of my projects.

Author: Yubico
Basename: libyubikey
Homepage: http://opensource.yubico.com/yubico-c/
License: BSD-2-Clause
Name: Yubico C low-level Library
Project: yubico-c
Summary: C library for manipulating Yubico YubiKey One-Time Passwords (OTPs)

The format is simple: UTF-8 text with each line starting with a header followed by a colon (“:”), some whitespace, and some content. If a line starts with whitespace, it is a continuation of the previous line’s content (trim leading whitespace). The following table describes the fields that I use. I may update this blog post in the future with new fields or improved explanations (for reference, current date is 2013-09-24).

Header Meaning
Project Short identifier for the project (e.g., ‘gcc’, ’emacs’)
Name Official name of the project in English
Summary Brief one-line summary of the project’s purpose in English
Author Origin of the project
Homepage URL to the project’s website
License License keyword, preferrably using one of the SPDX license identifiers
Basename The tarball basename, if different from the project name

Finally some reflection of the solution. After quick design, I thought that I couldn’t be the first one with this problem, and I tried to find other similar efforts. I haven’t been able to find any standardization effort that have the following properties:

  • Stores the information inside each upstream project’s own source code repository
  • Provides a filename convention so that it is possible to find the data with only the source code repository link
  • Encode data in a format that is easy to extract using simple command line tools
  • Not encode information about releases (i.e., what happened in a particular version)

The related efforts that I found were SPDX which at first look seemed to offer what I wanted. However on closer examination it failed to deliver on all the requirements above, and appeared to have somewhat different goals. However I found the SPDX license list useful and refer to it. Another effort is Eric S. Raymond’s freecode-submit and shipper but its primary focus is to encode information about each release. The design of the BLURB file is clearly influenced by these tools. Another influence has been Debian’s specification for machine-readable copyright information. The Free Software Foundation’s list of software projects seemed like another candidate, but it doesn’t suggest any way to store the information in the upstream project itself.

Posted in debian, programming | Tagged blurb, free software, metadata, project management, qa | 9 Replies

Primary Sidebar Widget Area

Recent Posts

  • OpenPGP master key on Nitrokey Start 2023-03-27
  • Apt Archive Transparency: debdistdiff & apt-canary 2023-02-01
  • Understanding Trisquel 2023-01-22
  • Preseeding Trisquel Virtual Machines Using “netinst” Images 2022-12-30
  • OpenPGP key on FST-01SZ 2022-12-24
  • Second impressions of Guix 1.4 2022-12-19
  • Guix 1.4 on NV41PZ 2022-12-16
  • Trisquel 11 on NV41PZ: First impressions 2022-12-10
  • How to complicate buying a laptop 2022-12-10
  • On language bindings & Relaunching Guile-GnuTLS 2022-10-14

Tag cloud

3g (3) android (7) debian (28) ed25519 (6) fsf (3) fst-01 (3) git (4) gnome (5) gnu (20) gnuk (7) gnupg (16) gnutls (4) gs2 (3) gsasl (5) gss-api (3) guix (3) i9300 (4) ietf (8) kerberos (3) key (4) keyring (3) laptop (5) lenovo (4) linux (5) neo (4) nv41pz (3) oath (3) openpgp (18) openwrt (6) pgp (4) pureos (5) replicant (7) rsa (5) s3 (5) sasl (8) scdaemon (3) security (14) smartcard (6) smartcards (4) ssh (3) sysadmin (3) trisquel (8) ubuntu (6) x201 (3) yubikey (6)

Archives

  • March 2023 (1)
  • February 2023 (1)
  • January 2023 (1)
  • December 2022 (6)
  • October 2022 (1)
  • September 2022 (1)
  • August 2022 (1)
  • July 2022 (1)
  • June 2021 (1)
  • May 2021 (1)
  • December 2019 (1)
  • June 2019 (1)
  • March 2019 (4)
  • August 2017 (1)
  • June 2017 (1)
  • March 2017 (1)
  • November 2016 (1)
  • December 2015 (1)
  • November 2015 (1)
  • October 2015 (1)
  • September 2015 (1)
  • June 2015 (1)
  • May 2015 (3)
  • March 2015 (2)
  • February 2015 (1)
  • January 2015 (2)
  • November 2014 (1)
  • August 2014 (3)
  • June 2014 (3)
  • February 2014 (1)
  • January 2014 (1)
  • November 2013 (1)
  • September 2013 (1)
  • October 2012 (1)
  • August 2012 (1)
  • December 2011 (1)
  • October 2011 (1)
  • May 2011 (1)
  • January 2011 (2)
  • November 2010 (1)
  • October 2010 (1)
  • September 2010 (1)
  • July 2010 (1)
  • May 2010 (1)
  • March 2010 (1)
  • January 2010 (1)
  • November 2009 (1)
  • October 2009 (1)
  • June 2009 (1)
  • April 2009 (1)
  • March 2009 (1)
  • October 2008 (3)
  • June 2008 (1)
  • May 2008 (1)
  • February 2008 (1)
  • January 2008 (2)
  • November 2007 (1)
  • October 2007 (2)
  • September 2007 (2)
  • August 2007 (3)
  • July 2007 (3)
  • June 2007 (2)
  • May 2007 (3)
  • April 2007 (7)
  • March 2007 (7)
  • October 2006 (3)
  • September 2006 (1)
Copyright © 2023 Simon Josefsson's blog. All Rights Reserved.
Theme: Catch Box by Catch Themes
Scroll Up