Hi, I packaged dozen of packages and I'm used to put LICENSE and README files just as: %doc README LICENSE which place these files in: /usr/share/doc/%{name}-%{version}
Recently I started packaging some rubygems and reviewers pointed [1,2] me that I should not explicitly move these files to this location and leave them in %{gem_instdir}. I do not feel it is correct behaviour.
I ran few statistics on my workstation:
I have 776 file with name LICENSE owned by some rpm package [3]. 631 packages have this file in /usr/share/doc/%{name}-%{version} [4] 145 packages have this file in different location [5] From this number 57 is rubygems packages [6] - out of 94 installed [7] So it is indeed very common for rubygems to have LICENSE in %{gem_instdir}. The other packages which have LICENSE in various paths are e.g. firefox: /usr/lib64/firefox/LICENSE or libreoffice: /usr/lib64/libreoffice/LICENSE or sos: /usr/share/sos/LICENSE or kde: /usr/share/kde4/apps/LICENSES/GPL_V2
I would like to ask: what should be correct location of LICENSE and README files. Should we standardize it (at least as SHOULD item)? Or give everyone liberty to put it anywhere he want and just flag it using %doc?
[1] https://bugzilla.redhat.com/show_bug.cgi?id=847504#c13 [2] https://bugzilla.redhat.com/show_bug.cgi?id=845805#c3 [3] rpm -qal | grep LICENSE | wc -l [4] rpm -qal |grep LICENSE |grep /usr/share/doc|wc -l [5] rpm -qal |grep LICENSE |grep -v /usr/share/doc|wc -l [6] rpm -qal |grep LICENSE |grep -v /usr/share/doc |grep /gems/|wc -l [7] rpm -qa |grep rubygem- |wc -l
On 08/16/2012 02:29 PM, Miroslav Suchy wrote:
Hi, I packaged dozen of packages and I'm used to put LICENSE and README files just as: %doc README LICENSE which place these files in: /usr/share/doc/%{name}-%{version}
Recently I started packaging some rubygems and reviewers pointed [1,2] me that I should not explicitly move these files to this location and leave them in %{gem_instdir}. I do not feel it is correct behaviour.
Agreed.
Though there can be reasons for not putting LICENSE and README files into %_docdir [1], I am inclined to believe the ruby packages's behavior to be a "bad habit" which ought to be abandoned.
Ralf
[1] Eg. READMEs may document files neighboring them. Forcing such READMEs into %_docdir doesn't make much sense, IMO.
Dne 16.8.2012 14:46, Ralf Corsepius napsal(a):
On 08/16/2012 02:29 PM, Miroslav Suchy wrote:
Hi, I packaged dozen of packages and I'm used to put LICENSE and README files just as: %doc README LICENSE which place these files in: /usr/share/doc/%{name}-%{version}
Recently I started packaging some rubygems and reviewers pointed [1,2] me that I should not explicitly move these files to this location and leave them in %{gem_instdir}. I do not feel it is correct behaviour.
Agreed.
Though there can be reasons for not putting LICENSE and README files into %_docdir [1], I am inclined to believe the ruby packages's behavior to be a "bad habit" which ought to be abandoned.
You should distinguish between Ruby packages and RubyGems packages, where Mirek actually refers to the later. Although this might be small difference to you, the reality is, that each RubyGem package reside in exactly one path, where Ruby package files goes to one shared directory with no strict naming conventions. So if you keep README from RubyGem package in the original location, they do not conflict, while if you would do the same for Ruby packages, there could be conflicts. So for Ruby packages, it makes sense to put them into /usr/share/doc while for RubyGems packages, it makes sense to keep the gem structure as close to the original gem as possible.
And there are other reasons why not move the documentation around:
* For every Ruby package, you can generate its documentation using RDoc. If you keep the license in the original place, the generated documentation will cover it, if you move it somewhere else, it will be missing from documentation.
* Metadata of the gem may refer to the documentation files. However I do not expect any issues in this area.
* Sometimes happens, that there is VERSION file which is referenced by code, which might cause broken behavior or library.
* It is more work.
Vit
Ralf
[1] Eg. READMEs may document files neighboring them. Forcing such READMEs into %_docdir doesn't make much sense, IMO.
-- packaging mailing list packaging@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/packaging
On Thu, Aug 23, 2012 at 10:49:06AM +0200, Vít Ondruch wrote:
- For every Ruby package, you can generate its documentation using
RDoc. If you keep the license in the original place, the generated documentation will cover it, if you move it somewhere else, it will be missing from documentation.
Might make sense to copy at least the LICENSE file to docdir (using %doc LICENSE), That installs two copies but will be quite handy to system admins who know their unix conventions but not ruby conventions and need to quickly access this sort of information. README and things that are about usage of the library I'm more ambivalent about. We seem to have two places where different sets of people would look. I think the ruby developers would be more interested in the usage instructions so their conventional location makes sense. OTOH, admins often have to make small changes to installed files to diagnose things or fix bugs. When that happens, they're surely going to be cursing the placement of the ruby documentation in a place they aren't expecting. Seems that we can't win that one.
- Metadata of the gem may refer to the documentation files. However I
do not expect any issues in this area.
- Sometimes happens, that there is VERSION file which is referenced
by code, which might cause broken behavior or library.
VERSION cannot be marked as %doc at all then. Anywhere it is marked as %doc needs to be fixed.
-Toshio
Dne 23.8.2012 17:09, Toshio Kuratomi napsal(a):
On Thu, Aug 23, 2012 at 10:49:06AM +0200, Vít Ondruch wrote:
- For every Ruby package, you can generate its documentation using
RDoc. If you keep the license in the original place, the generated documentation will cover it, if you move it somewhere else, it will be missing from documentation.
Might make sense to copy at least the LICENSE file to docdir (using %doc LICENSE), That installs two copies but will be quite handy to system admins who know their unix conventions but not ruby conventions and need to quickly access this sort of information.
Agree. Link could be even better then.
Vit
README and things that are about usage of the library I'm more ambivalent about. We seem to have two places where different sets of people would look. I think the ruby developers would be more interested in the usage instructions so their conventional location makes sense. OTOH, admins often have to make small changes to installed files to diagnose things or fix bugs. When that happens, they're surely going to be cursing the placement of the ruby documentation in a place they aren't expecting. Seems that we can't win that one.
- Metadata of the gem may refer to the documentation files. However I
do not expect any issues in this area.
- Sometimes happens, that there is VERSION file which is referenced
by code, which might cause broken behavior or library.
VERSION cannot be marked as %doc at all then. Anywhere it is marked as %doc needs to be fixed.
-Toshio
-- packaging mailing list packaging@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/packaging
Quoting Miroslav Suchy (2012-08-16 14:29:02)
The other packages which have LICENSE in various paths are e.g. firefox: /usr/lib64/firefox/LICENSE or libreoffice: /usr/lib64/libreoffice/LICENSE or sos: /usr/share/sos/LICENSE or kde: /usr/share/kde4/apps/LICENSES/GPL_V2
It's quite possible that firefox and/or kde use those files during runtime. So there should be possibility for an automatic exception in those cases. Other than that, I agree: %doc LICENSE is the way to go
packaging@lists.fedoraproject.org