Hi,
Updated
https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packaging/packagenames.rst
Le 31/05/2012 18:00, PJ Eby a écrit :
You've definitely put in a lot of work on this, and most of the actual
guidelines in your PEP are quite good. I think there's a core part of
this that can and should be a good Informational-track PEP.
If it actually becomes a draft PEP, I guess we should:
* move the document in PEPs' repository
* add notes in Python packaging documentation to reference the PEP.
However, I do have a few comments regarding overall organization, and
some regarding some of the specific recommendations and tone.
In order of appearance in the PEP, they are:
1. I would strongly suggest striking the aside on eggs entirely --
there's no point to bringing it up just to dismiss it, and there never
was such a thing as an "egg name" - eggs are just another kind of
distribution, so they don't need a special term.
Removed the text about eggs.
2. A project name isn't the name of a directory, it's the name of the
thing you release distributions of. E.g., my "Importing" project on
PyPI (http://pypi.python.org/pypi/Importing), which has the following
names:
a) Project name = Importing
b) Release = 1.10
c) Distribution = Importing-1.10.zip
d) Module = peak.util.imports
Following this conceptual breakdown will make the naming
recommendations easier to follow.
Changed "Terminology section".
However, I am still confusing "project name" and "distribution name".
From your comment, I understand that name argument of
packaging.core.setup() is the name of the project, which is used to get
names of the distributions like "%(project_name)s-%(version)s.tar.gz".
But PEP 345 says it is the name of the distributions :
http://www.python.org/dev/peps/pep-0345/#name
Also, I propose to shorten or move the "terminology" section in another
document (another pep or in packaging documentation):
* it would simplify the document
* we'd better share the terminology between several documents.
3. The rationale is unnecessary and could (and *should*) be cut
entirely. Use PEP 8 as a model - it doesn't waste time explaining why
coding guidelines are a good idea. The truth is, your PEP would be
massively improved simply by deleting this entire section and not even
trying to replace it with anything.
Changed the "Rationale" section:
* kept "relationship with other PEPs" and "other sources of inspiration".
* moved "opportunity" section from "Rationale" to "Transition plan"
section. I kept it because opportunity should be a valuable reason to
adopt the conventions. And unlike other statements of "Rationale",
opportunity cannot be explained within the conventions. Would you remove
it too?
* removed other text in the "Rationale" section.
4. The proposal section is also unnecessary, and likely to produce
resistance in any event.
The "proposal" part of "Rationale" section has been removed.
There is no reason why every package should use your approach,and some
developers will be opposed to your conventions.
"Rationale" section used to point out that current (missing) naming
rules lead to problems, such as duplicate packages/modules or
inconsistent project/package names. Shouldn't we consider them as issues?
But, whatever the value of those arguments, I understand some developers
will be opposed to proposed conventions.
That's why I tried to make the document tell:
* at last, in the namespace you own, you do what you want.
* at least (and at first), you should state on the conventions you are
currently using.
* then, understand the issues that names can introduce.
* optionally follow the proposed conventions, which may lead to renaming
project or packages/modules.
Since the document is a bit directive, the ideas above appear in
reversed order: first you should apply the convention, but at last you
do what you want to. Is it clear in the document?
Let's consider the "django-pipeline" VS "pipeline" VS "python-pipeline"
example:
* there is no obligation at all to rename these projects or packages.
* but one should admit there is an issue with names. Here the issue is a
duplicate package name. See
https://github.com/cyberdelia/django-pipeline/issues/101
* first of all, authors should be aware of the issue.
* then, if authors want to, they can apply conventions, which could be a
rename of the distributed package only.
* if django-pipeline changes its package or project name, it breaks the
"most used" scheme (de facto standard) of the Django community. So it
would be another homemade naming scheme...
* unless the Django community takes the naming issues into account,
states about packaging, and optionally promotes migrations.
Notice that Django community could state that "there is no valuable
issue, i.e. wontfix". But this would mean that this choice is documented
in an issue, discussion or in the documentation... so it would fit the
guidelines as an explicit community-specific convention.
(I disagree with some of them myself, for that matter, as I will
discuss below.) Some of the material from this section might make a
good later section on "How to apply these guidelines to your project".
The "proposal" section has been removed as part of the "Rationale" one.
Were you talking about the "Transition plan" instead?
I moved the "transition plan" section at the end of the document, i.e.
conventions appear before.
In fact, I changed the "transition plan" into a set of recipes for
existing projects.
5. The actual guidelines are pretty good, as I said. In particular, I
like pretty much every thing you say about package names. I disagree
with some of your assertions regarding project names, however. It's
true that a project name doesn't need to spell out what a project does
(as with Celery, Nose, etc.), but it does in fact hurt discovery and
use when people use package-based project names. It's a continuing
source of frustration, for example, that buildout recipe projects have
names like z3c.recipe.scripts and other names that I can't ever
remember, and am forced to re-google or dig up previous buildout files
to find the magic names to include in my buildouts. To me, the
important thing about a project name is that it be *memorable*, and
that argues against using namespaced package names as project names
for contributions to a larger project, such as Plone portlets,
Buildout recipes, etc.
This isn't a huge point of contention for me, I just want to point out
that the good naming choices for projects are more complicated than
"just use the package name and let people search for it". I think
there are some other points you made that are a little too
cut-and-dried in the same way, but this is the only really big one.
I updated the conventions:
* added an overview of conventions,
* introduced the "memorable" value.
I agree that choosing a "good" name is not easy. I suppose that the best
we can do is to provide guidelines such as "ownership", "memorable" or
"meaningful"... so that users can avoid some common pitfalls.
Then, it's a matter of priorities. I would say that:
1. first, we should avoid duplicates (project and packages). That's why
"top-level namespace for ownership" and "use a single name" seem so
important to me.
2. then, it's better if the project name is memorable and meaningful and
easy to discover... but it's a less important issue than duplicates,
mainly because other metadata such as description, keywords and
classifiers can help.
6. Drop the language about how things are supported or not supported.
This just isn't true: Python the language supports you nesting things
6 layers deep if you feel like it, and AFAIK there are no plans to
change that, nor should there be. Stick to talking here about what is
or isn't a good idea, not what's supported or not supported. That's
just FUD.
Removed "support" vocabulary.
Changed "conventions" to "guidelines".
Used only lowercase "may", "should" and "can".
7. PyPI should be the only place people have to check for a
registered distribution name; authors of projects that are hosted
elsewhere can and should use "setup.py register" to claim the name, or
log on and do it.
Added "Register names to PyPI" guideline.
Changed the "check for name availability" recipe: PyPI is the only place.
Anyway, as I said, I think you've got some really good stuff here,
but it's got a lot of other stuff hiding it. Cut away the extras (and
the parts implying these guidelines are mandatory) and you've got a
good Informational-track PEP.
Does it sounds better now?
Regards,
Benoit
_______________________________________________
Distutils-SIG maillist - [email protected]
http://mail.python.org/mailman/listinfo/distutils-sig
