Bug 632554 - Review Request: python-zope-component - Zope Component Architecture
Review Request: python-zope-component - Zope Component Architecture
Status: CLOSED RAWHIDE
Product: Fedora
Classification: Fedora
Component: Package Review (Show other bugs)
rawhide
All Linux
medium Severity medium
: ---
: ---
Assigned To: Toshio Ernie Kuratomi
Fedora Extras Quality Assurance
:
Depends On:
Blocks: 633138 634515
  Show dependency treegraph
 
Reported: 2010-09-10 07:09 EDT by Robin Lee
Modified: 2014-10-14 07:48 EDT (History)
5 users (show)

See Also:
Fixed In Version: python-zope-component-3.9.5-2.fc15
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2010-09-20 05:06:36 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---
a.badger: fedora‑review+
limburgher: fedora‑cvs+


Attachments (Terms of Use)

  None (edit)
Description Robin Lee 2010-09-10 07:09:55 EDT
Spec URL: http://cheeselee.fedorapeople.org/python-zope-component.spec
SRPM URL: http://cheeselee.fedorapeople.org/python-zope-component-3.9.5-1.fc13.src.rpm
Description:
This package represents the core of the Zope Component Architecture.
Together with the 'zope.interface' package, it provides facilities for
defining, registering and looking up components.

rpmlint results:

$ rpmlint ./python-zope-component.spec 
./python-zope-component.spec: W: no-cleaning-of-buildroot %install
./python-zope-component.spec: W: no-cleaning-of-buildroot %clean
./python-zope-component.spec: W: no-buildroot-tag
./python-zope-component.spec: W: no-%clean-section
0 packages and 1 specfiles checked; 0 errors, 4 warnings.

$ rpmlint ./python-zope-component-3.9.5-1.fc13.src.rpm 
python-zope-component.src: W: no-cleaning-of-buildroot %install
python-zope-component.src: W: no-cleaning-of-buildroot %clean
python-zope-component.src: W: no-buildroot-tag
python-zope-component.src: W: no-%clean-section
1 packages and 0 specfiles checked; 0 errors, 4 warnings.

$ rpmlint ./python-zope-component-3.9.5-1.fc13.noarch.rpm 
1 packages and 0 specfiles checked; 0 errors, 0 warnings.
Comment 1 Toshio Ernie Kuratomi 2010-09-16 13:38:23 EDT
Chen Lei, are you reviewing this?  I need it to enable unittests/optional features on another package so I'd be willing to review it if you want.  (The required packages have just been approved so I'm just figuring out if I should do this in the next few days or not.)
Comment 2 Chen Lei 2010-09-16 13:41:05 EDT
(In reply to comment #1)
> Chen Lei, are you reviewing this?  I need it to enable unittests/optional
> features on another package so I'd be willing to review it if you want.  (The
> required packages have just been approved so I'm just figuring out if I should
> do this in the next few days or not.)

Free feel to review it :), I'll help to review other python-zope-* packages.
Comment 3 Toshio Ernie Kuratomi 2010-09-16 23:24:51 EDT
Good:
* Package named according to the packaging guidelines
* Spec matches package name
* License is ZPLv2.1 in source and spec
* License file included in doc
* spec file readable
* Source matches upstream
* No locale specific files
* Not a shared library
* No bundled libraries
* Not relocatable
* Owns the files and direectories it creates and nothing more
* Permissions set properly
* Consistent use of macros
* code, not content.
* Not a GUI
* All filenames UTF-8
* builds in koji

NEEDSWORK:
* Documentation *.txt files in the module directory.  These should go to
  %docdir

rpmlint:
python-zope-component.src: W: no-cleaning-of-buildroot %install
python-zope-component.src: W: no-cleaning-of-buildroot %clean
python-zope-component.src: W: no-buildroot-tag
python-zope-component.src: W: no-%clean-section
2 packages and 0 specfiles checked; 0 errors, 4 warnings

You've been moving the *.txt files to %doc fine in the other zope packages so
I'll approve this and you can move them to %docdir when you import.

APPROVED
Comment 4 Chen Lei 2010-09-17 00:16:03 EDT
(In reply to comment #3)
> 
> NEEDSWORK:
> * Documentation *.txt files in the module directory.  These should go to
>   %docdir
> 
> 
> You've been moving the *.txt files to %doc fine in the other zope packages so
> I'll approve this and you can move them to %docdir when you import.
> 


It seems those files are not very useful if we put them into %{_docdir}, they are normally introductions for some particular files not introductions for the whole packages.

rpm -ql python|grep txt, you'll find python itself also add some txt files to module dir. 

e.g. fields.txt in zope.schema - it's a description for zope/schema/field.py, so it'll be much better to just leave them on module dir.
Comment 5 Toshio Ernie Kuratomi 2010-09-17 00:33:10 EDT
They do no good in the modules directory -- no one is expecting to look for them there.  So if they aren't doing any good in %{_docdir} then you might as well just rm them.

To me they look like they're documenting usage of the API, though, which could be useful.  In your prior package it seemed like you were recreating part of the directory structure so it seemed that people wanting to know how to use the API were able to see which file mapped to which module.
Comment 6 Toshio Ernie Kuratomi 2010-09-17 00:36:49 EDT
Bug opened for the main python package:
  https://bugzilla.redhat.com/show_bug.cgi?id=634809
Comment 7 Chen Lei 2010-09-17 03:28:08 EDT
(In reply to comment #5)
> They do no good in the modules directory -- no one is expecting to look for
> them there.  So if they aren't doing any good in %{_docdir} then you might as
> well just rm them.
> 
> To me they look like they're documenting usage of the API, though, which could
> be useful.  In your prior package it seemed like you were recreating part of
> the directory structure so it seemed that people wanting to know how to use the
> API were able to see which file mapped to which module.

It seems moving all .txt files to %{_docdir}/%{name}-%{version} directly is inappropriate.

Take python-zope-schema for a example:

./README.txt
./src/zope/schema/README.txt
./src/zope/schema/sources.txt
./src/zope/schema/index.txt
./src/zope/schema/validation.txt
./src/zope/schema/fields.txt
./CHANGES.txt
./LICENSE.txt
./COPYRIGHT.txt

The contents of ./README.txt and ./src/zope/schema/README.txt are different, we should not override ./README.txt with ./src/zope/schema/README.txt. 

From fields.txt - "This document highlights unusual and subtle aspects of various fields and field classes, and is not intended to be a general introduction to schema fields.", so obviously this .txt file is not a API docs for zope.schema package. It's normally useful when the developer want to take a look at the code of the fields.py. 

I'm not sure if it'll be clearer to recreate the directory structure under %{_docdir}[1] than just leaving those .txt files under module directory. 
It looks like those directory structures[1] are a bit complicated. I don't intend to oppose moving text files to %{_docdir}, however I think leaving some text files under python module directories is necessary and helpful[2]. Personally, I think leaving text files under %{_libdir}/python2.x/idlelib is reasonable.

[1]
e.g.

%{_docdir}/python-zope-schema-%{version}/zope/schema

%{_docdir}/python-%{version}/idlelib


[2]
e.g.

cat /usr/lib/python2.7/site-packages/README
This directory exists so that 3rd party packages can be installed
here.  Read the source for site.py for more details.
Comment 8 Toshio Ernie Kuratomi 2010-09-17 11:34:59 EDT
(In reply to comment #7)
> 
> It seems moving all .txt files to %{_docdir}/%{name}-%{version} directly is
> inappropriate.
> 
Agreed because of conflicting file.
> 
> From fields.txt - "This document highlights unusual and subtle aspects of
> various fields and field classes, and is not intended to be a general
> introduction to schema fields.", so obviously this .txt file is not a API docs
> for zope.schema package. It's normally useful when the developer want to take a
> look at the code of the fields.py. 
>
It's normally useful when a developer wants to make use of that API and it is not behaving the way they expect.  To me this is API documentation.... just not complete API documentation (ie: it tells how to use the API in complex cases, not in the easy, normal case.)
 
> I'm not sure if it'll be clearer to recreate the directory structure under
> %{_docdir}[1] than just leaving those .txt files under module directory. 
> It looks like those directory structures[1] are a bit complicated.

My view is that /usr/share/doc is where people look for documentation... anything helpful for them to read should be placed there.  %{python_sitelib} is not the place where people look for documentation so things that are helpful for users to read should not be left there.

> I don't
> intend to oppose moving text files to %{_docdir}, however I think leaving some
> text files under python module directories is necessary and helpful[2].
> Personally, I think leaving text files under %{_libdir}/python2.x/idlelib is
> reasonable.
> 
Looking over idlelib; the txt files appear to be data that is used within idle's help system so yes, those are necessary to the runtime operation of idle and belong in that directory and should not be marked %doc.

/me updates python bug so that that is not overlooked.
Comment 9 Robin Lee 2010-09-17 13:37:49 EDT
Thanks for you both.

New Package SCM Request
=======================
Package Name: python-zope-component
Short Description: Zope Component Architecture
Owners: cheeselee
Branches: el5 el6 f13 f14
InitialCC:
Comment 10 Kevin Fenzi 2010-09-19 15:25:42 EDT
Git done (by process-git-requests).
Comment 11 Ralph Bean 2014-10-13 21:05:52 EDT
Package Change Request
======================
Package Name: python-zope-component
New Branches: epel7
Owners: ralph
Comment 12 Jon Ciesla 2014-10-14 07:48:56 EDT
Git done (by process-git-requests).

Note You need to log in before you can comment on or make changes to this bug.