Framework metadata

[Giorgos Tsiapaliokas]

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=24a1920de41a3cf0b5c65d99efacf88433e88d96&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 at 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 at kde.org
> https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
>



-- 
Giorgos Tsiapaliokas (terietor)

terietor.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20131219/5165085c/attachment.html>