Framework metadata

[Alex Merry]

On 18/12/13 17:54, Aurélien Gâteau wrote:
> We need to have at least a COPYING file in there, with the full content of the 
> license.

I believe this was already done before the split.

> 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 like this idea.  The configuration stuff (read by KDE's apidox script)
in the bottom of Mainpage.dox should probably go in its own config file.

> 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.

Agreed.

> 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?

I'd be tempted to make a generic one that can just be dropped into every
framework, outlining the basic approach and pointing people towards our
wikis for more info.  Specifically, it should tell them to check CMake's
output for dependency information, as that will actually be accurate.

Alex