kde4 policy

Tue Feb 10 10:55:13 UTC 2009

Hello,

I just looked at the draft of the kde 4 apps policy Sune
committed at people/sune/doc/kde-policy some days ago.

There was some already some commenting in IRC from people usually reading the
commits mailing lists. Anyway, I reproduce the document here since it is
short,for the sake of people not reading it and so I can order my thoughts 
better. 

preface.tex 
------------------------------------------------------------------------------
\chapter{Preface}

This document documents how KDE packages should be named, described and packaged. The target audience of 
this document is mostly maintainers of applications that are not part of the official KDE releases.

Violations of this document does not allow filing of bugs with severity: serious or higher.

None of the sections in this document describes the packaging in the Debian releases Etch, Lenny or earlier releases, 
which all was shipped with a KDE Desktop with a major version lesser than 4. 
This document applies to KDE packaging targetted the Debian release Squeeze, but is expected to last at least as long as 
debian ships a KDE4 KDE Desktop.

The packages that are part of the official KDE releases does not yet fully adhere to this policy document, but is converging towards it.

This document uses shall and must and so on as defined in RFC 2119 \footnote{http://www.ietf.org/rfc/rfc2119.txt}
------------------------------------------------------------------------------
------------------------------------------------------------------------------

KDE should be KDE 4, even if we make it clearer below.

Describing what a "official KDE release" is sounds like a good idea. For some
people, stuff like amarok or koffice could fall in this category, when it does
not.

I would not link to the RFC and just direclty define what we meant with shall
and must.

apps.tex
------------------------------------------------------------------------------
\chapter{Applications}

\section{Naming}

All applications should be named as close to upstream project name, and if a version of a application using KDE3 libraries and a version using KDE4 libraries
is expected to coexist during the release cycle of ``Debian Squeeze'', the package name of the application using KDE3 libraries must be versioned.

\section{Description}

All packages should have a clear description that describes what the program do. The prases "\ldots for KDE" or "\ldots for KDE 4" should be avoided, unless
it is a package that doesn't make sense outside the KDE Desktop itself.

\section{Sections}

Unless the package is strictly for the KDE Desktop and should not be used outside the KDE Desktop, the application should not
be in section: kde, but in the appropriate section for the scope of the application.

\section{Dependecies}

Applications using the graphic user interface parts KDE Libraries must depend on the \emph{kdebase-runtime} package, as this package contains
data that the KDE Libraries expect to be available as well as some commands that KDE Libraries and application using KDE Libraries expects
to be around and uses unconditionally.
The shlibs system of the KDE library packages should make sure that this is in place, but if the application for some reason doesn't 
use the shlibs system, this must still be honoured.

------------------------------------------------------------------------------
------------------------------------------------------------------------------

Again KDE3 -> KDE 3 (and KDE4 -> KDE 4).

About naming: add some hints of how to rename the KDE 3 version of the app
consistently?  Specifying also here for source and binary packages.

About description: I do not see what is wrong with "for KDE X", you have a
thousand of apps that does almost the same, it is good to know what is the one
that will integrate better with your environment.
If I search for a notetaking app, I will get at least 10, but I will see that
kjots is "for KDE" so I will know it is better integrated in my KDE.

non-apps.tex
------------------------------------------------------------------------------
\chapter{Namings of non-application}

\section{Documentation of legacy}

In general, there is different types of non-application packages.
In KDE 3 series, there was mostly 
\begin{itemize}
\item Icon themes 
\item Widget styles 
\item Window decorations 
\end{itemize}
And in KDE3 series, these was named \emph{kde-icon-something}, \emph{kde-style-something}
and \emph{kwin-style-something}. If a source package built both a
widget style and a window decoration, the package could either build
two binaries, if a dependency on the KDE window manager was to be
avoided, or in one package named \emph{kde-style-something}

\section{Names}

In KDE4 series, there is at least the following types of third party
non-applications:
\begin{itemize}
\item Icon themes
\item Widget styles
\item Window decoration
\item Plasma data engines
\item Plasma script engines
\item Plasma widgets
\item KIO slaves
\end{itemize}
Icon themes should be named as \emph{kde-icon-something} if it is
a kde icon theme. KDE these days try to follow the freedesktop icon
specification.
\footnote{http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html}

The kde-icon-oxygen package is special though, as it also contains
all fallback icons for a KDE environment and a few KDE specific icons.

In general, third party icon themes should just be named \emph{something-icon-theme},
as they are usable in several desktop environments.

A KDE widget style must be named \emph{kde-style-something}, and
a window decoration for the KDE Window Manager must be named \emph{kwin-style-something}.
A binary package should in general not contain both a window decoration
and a widget style. \textbf{Examples}: kde-style-skulpture, kwin-style-skulpture.

Plasma dataengines must be in a \emph{plasma-dataengine-something}, just as Plasma widgets must be in 
a package called \emph{plasma-widget-something}, and Plasma scriptengines must be in a \emph{plasma-scriptengine-something}
package. If a data engine is specific to a widget and for now not meant to be shared among several widgets, 
the dataengine can be put into the same package as the widget.
Plasma containments can also be packages in a \emph{plasma-containment-something} package, if a \emph{plasma-widget-something} 
package isn't accurate enough.
\textbf{Examples:} plasma-widget-weather
Collections, as a source package building several related plasma parts, can be put in packages with a plural on the type, 
\textbf{Examples:} plasma-widgets-workspace

Third party KIO slaves should be placed in kio-something packages. \textbf{Example:} kio-ftps.

\section{Descriptions}

The description of the widget styles and the window decoration can contain a "\ldots for KDE" in the description, as these 
are specific to the group of KDE apps and usage of the KDE window manager.
KIO-slaves are used for all sorts of applications using KDE libraries and plasma thingies are also in the future to be shared
by multiple applications, and thus not specific to the KDE Desktop.
------------------------------------------------------------------------------
------------------------------------------------------------------------------

For all the stuff under "names", we have already kind of discussed it by IRC
earlier so not much to talk about here. It is some de facto policy already.
However, I would replace here the part where of the kind of package, name and 
example for a table for easy reading...

packaging.tex
------------------------------------------------------------------------------
\chapter{Packaging recommendation}

\section{Intro}

This chapter describes some recommendations on how to package applications built against libraries
from version 4 of the K Desktop Environment.

\section{Pkg-kde-tools}
It is recommended for packages built against libraries of KDE 4 to build depend on pkg-kde-tools 
and use the DEB\_CMAKE\_KDE4\_FLAGS variable as specified in 
\emph{/usr/share/pkg-kde-tools/makefiles/1/variables.mk} to get the default arguments for CMake for 
such packages. Please see \emph{/usr/share/doc/pkg-kde-tools/README.Debian} for more documentation

The \emph{variables.mk} snippet is for anyone packaging such applications. Some people prefers 
a build system called ``CDBS'', and \emph{/usr/share/pkg-kde-tools/makefiles/1/cdbs/kde.mk} is for such 
usage.
------------------------------------------------------------------------------
------------------------------------------------------------------------------

This section should contain (much) more info.... at least if we want people packaging
things correctly.
The "some people prefers..." is somehow personal and it should not be in a
policy text written in this way.

I can do some of the changes/improvments mentioned above. For the rest,
specially people reading this for first time, what do you think?

Ana