Get Involved/Quality/Plasma Applet Quality Guidelines

From KDE Community Wiki
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


These are some basic guidelines for plasma applets. Every applet should follow these to the extent possible.

General

Name

Naming a new plasmoid is a very important step and can be very hard. This is what a good name is like:

  • Short
  • Easy to pronounce
  • Not trademarked!
  • Make sure to ask native English speakers for hidden meaning
  • Optional: If the name is related to what the applet does people will remember it easier.

Comment

A comment is just that: a comment about the applet. Make it brief. (about 30 characters) Avoid repeating the name, we already know that, tell us what it does. If you need a bigger description use a wiki page or the kde-apps homepage for that.

Don't forget to spell check the comment!

Look and Feel

The default plasma theme is currently Air and it is thus very important that your applet looks good in Air and follows the plasma theme correctly. The oxygen theme is also used by a lot of users and is a bit darker (with white text) so make sure everything is readable.

Applets can be placed in different locations, consider all of them when testing it. The most used orientations are:

  • On the desktop
  • In a horizontal panel
  • In a vertical panel


Make sure nothing brakes when resizing (on the desktop)! Both when making it smaller and larger. Make sure it IS resizable, but give it a nice and good looking default size. Don't forget a minimum and maximum size.

When resizing in a panel you should not set a minimum size or it WILL break. (A maximum is not needed)

Configuration

Keep It Simple Stupid (KISS) Is that config option really needed? Every option should be obvious to what it does, a tooltip can make it easier to understand.

Translations

For translating you will depend on the community. Make the translaters job easy by using i18n calls where necessary. Depending on the purpose of the applet the biggest part of your target audience will be English (native or non native) so make sure the default text is in English.

The same goes for documentation in the code. That way other people can help out or learn from it.

Tip: use the x-test language to see if all strings can be translated.[[1]]

Installation

You can use the opendesktop.org framework to make a homepage for your applet on kde-look.org (see the plasmoid section) Applets that are hosted there can automatically be added to the desktop by users. This it done with GHNS. (Get Hot New Stuff) But this only works if its made in a scripted language (QML and JavaScript are advised) and in plasmapackage. Need link to techbase here.

Testing Checklist

Here is a checklist that you can use to see if an applet meets the quality requirements:

  • Name and description in "add applet" is correct
  • The comment is short but powerful
  • Looks good in Air ( and follows plasma theme correctly)
  • Looks good in Oxygen (and still readable)
  • Test on the desktop
    • Is the default size sensible?
    • Resize to the minimum size, does everything fit?
  • Test in a horizontal panel
    • Make the panel higher and smaller, does it fit?
  • Test in a vertical panel
    • Make the panel wider and thinner, does it fit?
  • Test editing config options
  • Right click on the plasmoid (is it sensible, try any additional entries)
  • Set a keyboard shortcut, does it do anything? Should it?
  • Test translations (X-test)
    • Main Widget
    • Config
    • Context menu
    • Name + Description when adding info
  • Can be installed with GHNS
  • Can be removed with GHNS
  • Are all existing bugs on this applet still valid? Close any which are not.

Reporting and Fixing Problems

If you are the developer please test your applet every major release. Problems with official plasma applets can be reported on bugs.kde.org for unofficial ones use the page on kde-look.org to post a comment. You can ask help in solving problems in the #plasma IRC channel. (be patient, try again a bit later if nobody responds right away)