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 <agat...@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
_______________________________________________ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
