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