Here's a low-barrier way to help improve FLOSS apps – AppStream metadata: Round 1

UPDATE: This program is full now!

We are so excited that we’ve got the number of volunteers we needed to assign all of the developer-related packages we identified for this round! THANK YOU! Any further applications will be added to a wait list (in case any of the assignees need to drop any of their assigned packages.) Depending on how things go, we may open up another round in a couple of weeks or so, so we’ll keep you posted!
Thanks again!!
— Mo, Ryan, and Hughsie


appstream-logo
Do you love free and open source software? Would you like to help make it better, but don’t have the technical skills to know where you can jump in and help out? Here is a fantastic opportunity!

The Problem

There is an cross-desktop, cross-distro, Freedesktop.org project called AppStream. In a nutshell, AppStream is an effort to standardize metadata about free and open source applications. Rather than every distro have its own separate written description for Inkscape, for example, we’d have a shared and high-quality description of Inkscape that would be available to users of all distros. Why is this kind of data important? It helps free desktop users discover applications that might meet their needs – for example, via searching software center applications (such as GNOME Software and Apper.)

Screenshot of GNOME Software showing app metadata in action!
Screenshot of GNOME Software showing app metadata in action!

Running this project in a collaborative way is also a great way for us to combine efforts and come up with great quality content for everyone in the FLOSS community.
Contributors from Fedora and other distros have been working together to build the infrastructure to make this project work. But, we don’t yet have even close to full metadata coverage of the thousands of FLOSS applications we ship. Without metadata for all of the applications, users could be missing out on great applications or may opt out of installing an app that would work great for them because they don’t understand what the app does or how it could meet their needs.

The Plan

Ryan Lerch among other contributors have been working very hard for many weeks now generating a lot of the needed metadata, but as of today only have roughly 25% coverage for the desktop packages in Fedora. We’d love to see that number increase significantly for Fedora 21 and beyond, but we need your help to accomplish that!
Ryan, Richard Hughes, and I recently talked about the ongoing effort. Progress is slower than we’d like, we have less contributors than we’d like – but it is a great opportunity for new contributors, because of the low barrier to entry and big impact the work has!
So along that line, we thought of an idea for an ongoing program that we’d like to pilot: Basically, we’ll chunk the long list of applications that need the metadata into thematic lists – for example, graphics applications, development applications, social media applications, etc. etc. Each of those lists we’ll break into chunks of say 10 apps each, and volunteers can pick up those chunks and submit metadata for just those 10.
The specific metadata we are looking for in this pilot is a brief summary about what the application is and a description of what the application does. You do not need to be a coder to help out; you’ll need to be able and willing to research the applications in your chunk and draft an openly-licensed paragraph (we’ll provide specific guidelines) and submit it via a web form on github. That’s all you need to do.
This blog post will kick off our pilot (“round 1”) of this effort, and we’ll be focusing on applications geared towards developers.

Your mission

If you choose to participate in this program, your mission will be to research and write up both brief summaries about and long-form descriptions for each of ~10 free and open source applications.
You might want to check out the upstream sites for each application, see if any distros downstream have descriptions for the app, maybe install and try the app out for yourself, or ask current users of the app about it and its strengths and weaknesses. The final text you submit, however, will need to be original writing created by you.

Specifications

Summary field for application

The summary field is a short, one-line description of what the application enables users to do:

  • It should be around 5 – 12 words long, and a single sentence with no ending punctuation.
  • It should start with action verbs that describe what it allows the user to do, for example, “Create and edit Scalable Vector Graphics images” from the Inkscape summary field.
  • It shouldn’t contain extraneous information such as “Linux,” “open source,” “GNOME,” “gtk,” “kde,” “qt,” etc. It should focus on what the application enables the user to do, and not the technical or implementation details of the app itself.
Examples

Here are some examples of good AppStream summary metadata:

  • “Add or remove software installed on the system” (gpk-application / 8 words)
  • “Create and edit Scalable Vector Graphics images” (Inkscape / 7 words)
  • “Avoid the robots and make them crash into each other” (GNOME Robots / 10 words)
  • “View and manage system resources” (GNOME System Monitor / 5 words)
  • “Organize recipes, create shopping lists, calculate nutritional information, and more.” (Gourmet / 10 words)

Description field for application

The description field is a longer-form description of what the application does and how it works. It can be between 1 – 3 short paragraphs / around 75-100 words long.

Examples

Here are some examples of good AppStream description metadata:

  • GNOME System Monitor / 76 words:
    “System Monitor is a process viewer and system monitor with an attractive, easy-to-use interface.
    “System Monitor can help you find out what applications are using the processor or the memory of your computer, can manage the running applications, force stop processes not responding, and change the state or priority of existing processes.
    “The resource graphs feature shows you a quick overview of what is going on with your computer displaying recent network, memory and processor usage.”
  • Gourmet / 94 words:
    “Gourmet Recipe Manager is a recipe-organizer that allows you to collect, search, organize, and browse your recipes. Gourmet can also generate shopping lists and calculate nutritional information.
    “A simple index view allows you to look at all your recipes as a list and quickly search through them by ingredient, title, category, cuisine, rating, or instructions.
    “Individual recipes open in their own windows, just like recipe cards drawn out of a recipe box. From the recipe card view, you can instantly multiply or divide a recipe, and Gourmet will adjust all ingredient amounts for you.”
  • GNOME Robots / 102 words:
    “It is the distant future – the year 2000. Evil robots are trying to kill you. Avoid the robots or face certain death.
    “Fortunately, the robots are extremely stupid and will always move directly towards you. Trick them into colliding into each other, resulting in their destruction, or into the junk piles that result. You can defend yourself by moving the junk piles, or escape to safety with your handy teleportation device.
    “Your supply of safe teleports is limited, and once you run out, teleportation could land you right next to a robot, who will kill you. Survive for as long as possible!”

Content license

These summaries and descriptions are valuable content, and in order to be able to use them, you’ll need to be willing to license them under a license such that the AppStream project and greater free and open source software community can use them.
We are requesting that all submissions be licensed under the Creative Commons’ CC0 license.

What’s in it for you?

Folks who contribute metadata to this effort through this program will be recognized in the upstream appdata credits as official contributors to the project and will also be awarded a special Fedora Badges badge for contributing appdata!
appstream
When this pilot round is complete, we’ll also publish a Fedora Magazine article featuring all of the contributors – including you!
Oh, and of course – you’ll be making it easier for all free and open source software users (not just Fedora!) to find great FLOSS software and make their lives better! 🙂

Sign me up! How do I get started?

help-1

  1. First, if you don’t have one already, create an account at GitHub.
  2. In order to claim your badge and to interact with our wiki, you’ll need a Fedora account. Create a Fedora account now if you don’t alrady have one.
  3. Drop an email to appstream at lists dot fedoraproject [.] org with your GitHub username and your Fedora account username so we can register you as a contributor and assign you your applications to write metadata for!
  4. For each application you’ll need to write metadata for, we’ve generated an XML document in the Fedora AppStream GitHub repo. We will link you up to each of these when we give you your assignment.
  5. For each application, research the app via upstream websites, reviews, talking to users, and trying out the app for yourself, then write up the summary and description fields to the specifications given above.
  6. To submit your metadata, log into GitHub and visit the XML file for the given application we gave you in our assignment email. Take a look at this example appstream metadata file for an application called Insight. You’ll notice in the upper right corner there is an ‘Edit’ button – click on this, edit the ‘Summary’ and ‘Description’ fields, edit the copyright statement towards the very top of the file with your information, and then submit them using the form at the bottom.

Once we’ve received all of your submissions, we’ll update the credits file and award you your badge. 🙂
If you end up commiting to a batch of applications and end up not having the time to finish, we ask that you let us know so we can assign the apps to someone else. We’re asking that you take two weeks to complete the work – if you need more time, no problem, let us know. We just want to make sure we reopen up assigned apps for others to join in and help out with.

Let’s do this!

Ready to go? Drop us a line!

31 Comments

  1. Miro Hrončok says:

    I guess contributing directly to upstream is still preferred? Can we get a badge for that as well, or do I need to do it in this complicated way?

    1. mairin says:

      Hey Miro – sorry for the delay in replying, apparently the WordPress android app eats comments for lunch 🙁
      We are happy to grant you a badge for any help you can give us in working with the AppStream metadata – if you’d like to work with the upstreams, we even have metadata we haven’t pushed to the upstreams yet we could use help with. You’re welcome to do the metadata work too, outside of this process if you’d like.
      The reason we left the upstream component out this round is two-fold:
      – We don’t just have one upstream – every application is an upstream. So it’s contacting and coordinating a lot of communication and that may span much longer than the 2-week commitment we wanted to keep this activity too. We also wanted it to be relatively low-barrier to help new contributors join in.
      – We don’t yet have a good way to track which upstreams have been contacted and which haven’t – without this framework in place we might bug the same upstream multiple times which would be annoying for them. If you have ideas on infrastructure / process we can set up to manage this we are very grateful for help on that too.
      Anyway in a nutshell – yes, contributing to upstream is really important here, but we’ve been slogging about it slowly & manually and don’t have a great process for it, and also yes, we would love to give you a badge for any help you are willing to contribute!

  2. Hello,
    Why isn’t there a panel where we just enter the metadata in defined fields; somewhat similar to translations workflow. (transifex, crowdin, launchpad, etc)?

    1. mairin says:

      It would be awesome if there was – would you be interested in developing such a thing? 🙂 ?

  3. […] Here’s a low-barrier way to help improve FLOSS apps – AppStream metadata: Round 1 […]

  4. […] Duffy na svém blogu píše o jednoduchém způsobu, jak pomoci otevřenému a svobodnému softwaru – můžete přispívat metadata pro AppStream. AppStream je formát, který poskytuje […]

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.