[Distutils] conventions or best practice to choose package names?

[Benoît Bryon]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20120606/075f520e/attachment.html>