[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-frameworks-devel
Subject: Re: Framework metadata
From: Giorgos Tsiapaliokas <terietor () gmail ! com>
Date: 2013-12-19 10:13:08
Message-ID: CAODYyLZJoWi-t0d-1eE5yCDELxf90W8R917=CaAe6sfX79un6w () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
I definitely like the idea but I don't like xml/rdf. Why don't we just use
json?
Qt is already using json and the
logical-module-structure<http://quickgit.kde.org/?p=kde-build-metadata.git&a=blob&h=24 \
a1920de41a3cf0b5c65d99efacf88433e88d96&hb=c31e1c9048be76b282de8421d51b6e5bed2809b5&f=logical-module-structure>of
kde-build-metadata is using json.
*Please* lets avoid using ancient and unreadable formats :)
On 18 December 2013 19:54, Aurélien Gâteau <agateau@kde.org> wrote:
> 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
> _______________________________________________
> Kde-frameworks-devel mailing list
> Kde-frameworks-devel@kde.org
> https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
>
--
Giorgos Tsiapaliokas (terietor)
terietor.org
[Attachment #5 (text/html)]
<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=24a1920de41a3 \
cf0b5c65d99efacf88433e88d96&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>
_______________________________________________
Kde-frameworks-devel mailing list
Kde-frameworks-devel@kde.org
https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic