<div dir="ltr">I definitely like the idea but I don't like xml/rdf. Why don't we just use json? <div>Qt is already using json and the <a href="http://quickgit.kde.org/?p=kde-build-metadata.git&a=blob&h=24a1920de41a3cf0b5c65d99efacf88433e88d96&hb=c31e1c9048be76b282de8421d51b6e5bed2809b5&f=logical-module-structure">logical-module-structure</a> of kde-build-metadata is using json.</div>
<div><br></div><div>*Please* lets avoid using ancient and unreadable formats :)</div><div><br></div><div><br></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On 18 December 2013 19:54, Aurélien Gâteau <span dir="ltr"><<a href="mailto:agateau@kde.org" target="_blank">agateau@kde.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi,<br>
<br>
I'd like to gather opinions regarding the split task "Ensure all the necessary<br>
files are in place in each framework (README, license, apidox, etc. etc.)",<br>
especially defining the "etc. etc." part :)<br>
<br>
## Intro<br>
<br>
I think the information we want to provide for each framework is to define the<br>
following:<br>
<br>
- The goal of the framework<br>
<br>
- Its license<br>
<br>
- How to use it<br>
<br>
- Libraries it depends on<br>
<br>
- How to report bugs<br>
<br>
- How to contribute<br>
<br>
- Anything else?<br>
<br>
## DOAP<br>
<br>
To avoid duplication as much as possible and to provide machine-readable<br>
information, I suggest we use a standard file format like DOAP to describe the<br>
framework. DOAP stands for Definition Of A Project, it is an RDF schema to<br>
describe a project. You can learn more about it from:<br>
<br>
<a href="https://github.com/edumbill/doap/wiki" target="_blank">https://github.com/edumbill/doap/wiki</a><br>
<br>
DOAP is already used by the Apache and GNOME projects. The nice thing about<br>
using such a format is that it is easy to extend. For example GNOME is<br>
extending it to include the user id of the project maintainers:<br>
<br>
<a href="https://git.gnome.org/browse/glib/tree/glib.doap" target="_blank">https://git.gnome.org/browse/glib/tree/glib.doap</a><br>
<br>
This means we can extend it to include framework-specific information like its<br>
tier (1, 2, 3, 4) and type (solution, integration, functional). Then apidox<br>
can extract useful information from it to populate the framework home page and<br>
generate library dependency diagrams.<br>
<br>
The information in the DOAP file can also be used to generate manifest files<br>
for Inqlude (<a href="http://inqlude.org/" target="_blank">http://inqlude.org/</a>)<br>
<br>
## What about traditional files?<br>
<br>
We need to have at least a COPYING file in there, with the full content of the<br>
license.<br>
<br>
Then there is the README file. Historically we haven't been very good at<br>
keeping them up to date, have a look at the current ones for a trip back<br>
memory lane.<br>
<br>
I think the only way to make them relevant is to integrate them in the<br>
documentation through apidox. This way the README content would be visible in<br>
the home page of the framework on <a href="http://api.kde.org" target="_blank">api.kde.org</a>, similar to how github promotes<br>
README files (which is IMHO a nice idea). It makes even more sense to do this<br>
now that Doxygen supports Markdown, allowing us to write high-level<br>
documentation in README.md files rather than in a Mainpage.dox file which is<br>
just a big C comment.<br>
<br>
I would avoid adding any Changelog file as this information is better provided<br>
by git history nowadays.<br>
<br>
Same for NEWS file. There is value in having a more concise list of changes<br>
between versions, but I am quite sure those files would not get updated.<br>
<br>
What about the INSTALL file? Most frameworks are going to have a<br>
straightforward "mkdir build ; cd build ; cmake .. ; make install" procedure.<br>
Do we want to document this as well? Does it need its own file or can it go in<br>
the README?<br>
<br>
Thoughts?<br>
<br>
Aurélien<br>
_______________________________________________<br>
Kde-frameworks-devel mailing list<br>
<a href="mailto:Kde-frameworks-devel@kde.org">Kde-frameworks-devel@kde.org</a><br>
<a href="https://mail.kde.org/mailman/listinfo/kde-frameworks-devel" target="_blank">https://mail.kde.org/mailman/listinfo/kde-frameworks-devel</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Giorgos Tsiapaliokas (terietor)<br><br><a href="http://terietor.org" target="_blank">terietor.org</a></div>
</div>