Framework metadata

[Aurélien Gâteau]

Hi,

I'd like to gather opinions regarding the split task "Ensure all the necessary 
files are in place in each framework (README, license, apidox, etc. etc.)", 
especially defining the "etc. etc." part :)

## Intro

I think the information we want to provide for each framework is to define the 
following:

- The goal of the framework

- Its license

- How to use it

- Libraries it depends on

- How to report bugs

- How to contribute

- Anything else?

## DOAP

To avoid duplication as much as possible and to provide machine-readable 
information, I suggest we use a standard file format like DOAP to describe the 
framework. DOAP stands for Definition Of A Project, it is an RDF schema to 
describe a project. You can learn more about it from:

  https://github.com/edumbill/doap/wiki

DOAP is already used by the Apache and GNOME projects. The nice thing about 
using such a format is that it is easy to extend. For example GNOME is 
extending it to include the user id of the project maintainers:

  https://git.gnome.org/browse/glib/tree/glib.doap

This means we can extend it to include framework-specific information like its 
tier (1, 2, 3, 4) and type (solution, integration, functional). Then apidox 
can extract useful information from it to populate the framework home page and 
generate library dependency diagrams.

The information in the DOAP file can also be used to generate manifest files 
for Inqlude (http://inqlude.org/)

## What about traditional files?

We need to have at least a COPYING file in there, with the full content of the 
license.

Then there is the README file. Historically we haven't been very good at 
keeping them up to date, have a look at the current ones for a trip back 
memory lane.

I think the only way to make them relevant is to integrate them in the 
documentation through apidox. This way the README content would be visible in 
the home page of the framework on api.kde.org, similar to how github promotes 
README files (which is IMHO a nice idea). It makes even more sense to do this 
now that Doxygen supports Markdown, allowing us to write high-level 
documentation in README.md files rather than in a Mainpage.dox file which is 
just a big C comment.

I would avoid adding any Changelog file as this information is better provided 
by git history nowadays.

Same for NEWS file. There is value in having a more concise list of changes 
between versions, but I am quite sure those files would not get updated.

What about the INSTALL file? Most frameworks are going to have a 
straightforward "mkdir build ; cd build ; cmake .. ; make install" procedure. 
Do we want to document this as well? Does it need its own file or can it go in 
the README?

Thoughts?

Aurélien