Laca: > On Wed, 2007-12-12 at 19:05 -0600, Brian Cameron wrote: > >> Questions include: > >> - Briefly describe the functionality provided by the open >> source technology? > > It would be a good idea to fill the %description field with > this information.
Yes, I agree that putting all the information into the spec files makes sense, and makes things easy for report generation, etc. >> - Is the open source technology an implementation of an industry >> standard? >> >> Note that code that supports any proprietary software or >> hardware should be mentioned. For example, device support >> or support of a particular format, or a codec. > > This is a bit more work. Yes, and perhaps also something that should/could be mentioned in the %description. >> - Without doing any research, are you aware of any patent or >> copyright lawsuits or claims relating to the open source >> technology? >> >> - What is the license? Provide the full text. > > Instead of providing the full text, perhaps we could just fill in > the License field in all spec files and maybe add a URL to the > license where it's not one of the widely used ones. That seems fine as long as the license for a module doesn't have any exceptions, or other deviations from the normal license. In such cases, the spec file could perhaps highlight what differences exist in the %description or something. >> - What is the abstraction layer between the code and the rest >> of the system? How is the code segregated from the rest of >> the system? For example, it is inappropriate to link non-GPL >> code into a GPL program. Explain any such issues. > > Grr... I was always unsure what to write in this box (: I believe that the point of this question is just to ensure that you don't link things inappropriately. For example, when adding a GPL library, there needs to be some effort to make sure that nothing we ship links against it that isn't GPL. For example, we shouldn't link CDDL or LGPL programs with a GPL library, etc. >> - Pointers to any documentation, websites, project home pages >> that should be used to reference the project. > > We already have the URL field filled in for most modules. Can the URL field contain multiple URL's if there are multiple points of documentation? I thought the URL field was more for the project homepage rather than any specific documentation pages. Also note that some docs aren't on the web, such as installed gtk-docs. I'm not sure the URL field makes sense for pointing to such docs? >> That doesn't seem like a burdensome amount of work to expect >> someone to do if they wish to be an OpenSolaris module maintainer. > > Well, it's not very exciting to do this paperwork, the good news is > that it's usually only needed once. Agreed it is not exciting, but it is the sort of sanity check any distro should do before adding a module to the OS, I think. >> Perhaps we could set aside a spot on the OpenSolaris Wiki to store >> this information so it can be referenced and easy to put together. >> Helping with this work would be of great assistance to getting >> any modules into Nevada. > > I think the spec file itself is the best place for this information. I agree. Though I wonder if we might need to add some new keys or tagging mechanisms in the spec file to deal with how to document programs that use GPL license exceptions and how to reference module documentation. >> Another process that is useful is the ARC (Architecture Review >> Committee) process, where we document and review module interfaces. > > Right. We could possibly also include a list of imported and exported > interfaces in the spec file. Really manpages should do this. Note that library (section 3) manpages can refer to gtk-docs. If the manpages are well written and complete, then the interfaces are well enough documented to make ARC happy. Rather than focusing on OpenSolaris spec file maintainers doing special ARC documentation, I'd prefer if they were just involved to ensure that the manpages were complete and accurate and we can internally build ARC documents from the manpage information as needed. This way OpenSolaris spec file maintainers can focus more on community involvement and less on the Sun specific aspects of things. Brian
