As noted when we were giving FPC latest Java guidelines to review, we are in process of restructuring them in more significant ways.
One of the most important aspects is moving documentation of tools outside of guidelines. Some parts of current Java guidelins[1-6] are prime examples of things that we are planning to move out of guidelines and into separate "Java Packaging HOWTO" document.
Other guidelines probably don't suffer from this as much as Java ones (50% of text is description of how to use tools), but still...
Goal is of course not to circumvent Fedora policies but make sure that guidelines contain the policy, whereas real documentation contains descriptions of how to do things. In other words guidelines should IMO contain *what* (not) to do, and other documents should tell packagers *how* to do it.
Any thoughts on the matter? It will be some time before we submit an update to guidelines either way, but I like early feedback :-)
[1] https://fedoraproject.org/wiki/Packaging:Java#add_maven_depmap_macro [2] https://fedoraproject.org/wiki/Packaging:Java#Additional_mappings [3] https://fedoraproject.org/wiki/Packaging:Java#Alternative_JAR_file_names [4] https://fedoraproject.org/wiki/Packaging:Java#Single_artifact_per_package [5] https://fedoraproject.org/wiki/Packaging:Java#Assignment_of_the_Maven_artifa... [6] https://fedoraproject.org/wiki/Packaging:Java#Patching_Maven_pom.xml_files
"SO" == Stanislav Ochotnicky sochotnicky@redhat.com writes:
SO> Goal is of course not to circumvent Fedora policies but make sure SO> that guidelines contain the policy, whereas real documentation SO> contains descriptions of how to do things. In other words guidelines SO> should IMO contain *what* (not) to do, and other documents should SO> tell packagers *how* to do it.
Yes, of course, this is an excellent idea. Too much stuff in the guidelines not only bloats them beyond reason but makes it difficult to make changes to what should be easily editable documentation.
What's important to keep is enough information so that packagers understand what they should do, and reviewers can tell if what they're seeing is done correctly. Pretty much everything else should be outside the guidelines.
- J<
packaging@lists.fedoraproject.org