Re: Naming guidelines for ELPA packages

Re: Naming guidelines for ELPA packages

[Philip Kaludercic]

Jim Porter <jporterbugs@gmail.com> writes:

> On 5/13/2023 3:30 PM, Richard Stallman wrote:
>> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
>> [[[ whether defending the US Constitution against all enemies,     ]]]
>> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>>    > How about something like "devil-keys"? That should make it
>> clear that
>>    > the package has something to do with keys. It doesn't tell exactly what
>>    > it *does* with those keys, but I think a more-detailed description
>>    > belongs in the package description or the manual.
>> I like this way of serving both goals at once: a clue about what the
>> job is,
>> and a name to distinguish this package from others for thatjob.
>> 
>
> Maybe we could turn this into a general guideline, and document it
> somewhere on GNU ELPA (maybe the README). Something like the below? It
> could probably use some editorial work, but I thought an example
> "story" of choosing a package name might help explain things to
> readers.

I've suggested something like this in the past, but I can't find my
message.  Either way, I think this is a good idea that could help avoid
a lot of bikeshedding.

> ----------------------------------------
>
> Naming is hard. To assist package authors, here are some guidelines
> for choosing good Emacs package names. Package names should be:
>
>   * Memorable: Aim for short, distinct names that users can easily recall.
>   * Intuitive: Names don't need to fully describe a package, but they
>     should at least provide a hint about what the package does.
>
> For example, suppose I've written a package that provides an interface
> between GObjects and Emacs Lisp, and named it "goeli". This isn't a
> very good name, since it's not easy to remember (users may find
> themselves asking, "Wait... was it 'goli' or 'goeli'?"), and it's
> nearly impossible to guess what it does from the name.
>
> After thinking about it some more, I have a flash of insight: I'll
> call it "goblin" (for _GOb_ject _L_isp _In_terface)! This is easy
> enough to remember, but it's still not intuitive.
>
> Perhaps the best name for a package like this would simply be
> "gobject". That's both memorable *and* intuitive.
>
> However, after thinking about it yet again, I find myself
> disappointed: while "gobject" is a thoroughly practical name, it's
> just not very fun. Instead, I finally opt for a compromise: I'll still
> use "Goblin" when documenting the package and prefix names in my code
> with "goblin-", but I decide to submit it to GNU ELPA as
> "goblin-functions". While this isn't as descriptive as "gobject", it
> does at least provide a hint to the reader that this is a collection
> of functions (intended for other Lisp authors, as opposed to end
> users).


I agree with everything up until the last paragraph, but am not
convinced that encouraging a "fun name" should be part of the
guidelines.

Re: Naming guidelines for ELPA packages

[Jim Porter]

On 5/14/2023 12:47 AM, Philip Kaludercic wrote:
> I agree with everything up until the last paragraph, but am not
> convinced that encouraging a "fun name" should be part of the
> guidelines.

I think I need to adjust the passage a bit to emphasize that the 
Emacs/ELPA maintainers would *prefer* a simple and straightforward name 
like "gobject". However, I also think it's important to show how you can 
come up with a good compromise if you're a package author who just can't 
let go of your fun package name. In my mind, showing in the 
documentation how to compromise on this would go a long way towards 
making package authors not feel like they're being micromanaged.

Re: Naming guidelines for ELPA packages

[Philip Kaludercic]

Jim Porter <jporterbugs@gmail.com> writes:

> On 5/14/2023 12:47 AM, Philip Kaludercic wrote:
>> I agree with everything up until the last paragraph, but am not
>> convinced that encouraging a "fun name" should be part of the
>> guidelines.
>
> I think I need to adjust the passage a bit to emphasize that the
> Emacs/ELPA maintainers would *prefer* a simple and straightforward
> name like "gobject". However, I also think it's important to show how
> you can come up with a good compromise if you're a package author who
> just can't let go of your fun package name. In my mind, showing in the
> documentation how to compromise on this would go a long way towards
> making package authors not feel like they're being micromanaged.

That would sound acceptable to me.

Re: Naming guidelines for ELPA packages

[Stefan Monnier via Emacs development discussions.]

> Naming is hard.  To assist package authors, here are some guidelines for
> choosing good Emacs package names.  Package names should be:
>
>   * Memorable: Aim for short, distinct names that users can easily recall.
>   * Intuitive: Names don't need to fully describe a package, but they should
>    at least provide a hint about what the package does.

I can go along guidelines to *help* maintainers choose good
package names.  But I think it's very important that we refrain from
*imposing* it on maintainers.

So if the author prefers to stick with `devil`, then that's what it'll
be.  We have much more important things to worry about when it comes to
imposing guidelines (e.g. making sure that the package doesn't overstep
its namespace).


        Stefan

Re: Naming guidelines for ELPA packages

[Jim Porter]

On 5/14/2023 2:36 PM, Stefan Monnier via Emacs development discussions. 
wrote:
>> Naming is hard.  To assist package authors, here are some guidelines for
>> choosing good Emacs package names.  Package names should be:
>>
>>    * Memorable: Aim for short, distinct names that users can easily recall.
>>    * Intuitive: Names don't need to fully describe a package, but they should
>>     at least provide a hint about what the package does.
> 
> I can go along guidelines to *help* maintainers choose good
> package names.  But I think it's very important that we refrain from
> *imposing* it on maintainers.
> 
> So if the author prefers to stick with `devil`, then that's what it'll
> be.  We have much more important things to worry about when it comes to
> imposing guidelines (e.g. making sure that the package doesn't overstep
> its namespace).

I agree. This is mainly an attempt to help package maintainers pick good 
(or "good enough") names on their own so that there's less time spent 
discussing this issue, and also to be upfront about what the Emacs/ELPA 
maintainers would prefer. That way, as a package maintainer, you can 
take these guidelines into account (or not) before you even submit the 
package.

Re: Naming guidelines for ELPA packages

[Stefan Monnier]

> I agree. This is mainly an attempt to help package maintainers pick good (or
> "good enough") names on their own so that there's less time spent discussing
> this issue, and also to be upfront about what the Emacs/ELPA maintainers
> would prefer. That way, as a package maintainer, you can take these
> guidelines into account (or not) before you even submit the package.

Great.  Is there still something that needs to be resolved before we can
add this package to NonGNU ELPA, then?
[ BTW, I wish this went into GNU ELPA, instead.  Oh, and it should have
  a `.gitignore` along the lines of what I put in the appended patch.  ]


        Stefan


diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000..af7e30dd09
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+/devil-autoloads.el
+/devil-pkg.el
+*.elc

Re: Naming guidelines for ELPA packages

[Jim Porter]

On 5/14/2023 4:00 PM, Stefan Monnier wrote:
>> I agree. This is mainly an attempt to help package maintainers pick good (or
>> "good enough") names on their own so that there's less time spent discussing
>> this issue, and also to be upfront about what the Emacs/ELPA maintainers
>> would prefer. That way, as a package maintainer, you can take these
>> guidelines into account (or not) before you even submit the package.
> 
> Great.  Is there still something that needs to be resolved before we can
> add this package to NonGNU ELPA, then?

In my opinion, no. I only suggested 'devil-keys' as a compromise that 
could address the concerns people had about the name 'devil' not 
providing a hint about what the package does. (In this subthread, I 
mainly wanted to discuss whether we could come up with a general 
guideline to assist package authors in coming up with reasonably-good 
names.)

But then I'm not exactly an authority figure on what does and doesn't go 
into ELPA. :)

Re: Naming guidelines for ELPA packages

[Drew Adams]

> I can go along guidelines to *help* maintainers choose good
> package names.  But I think it's very important that we refrain from
> *imposing* it on maintainers.
> 
> So if the author prefers to stick with `devil`, then that's what it'll
> be.  We have much more important things to worry about when it comes to
> imposing guidelines (e.g. making sure that the package doesn't overstep
> its namespace).

This.

Let users know the rationale behind the guideline,
in particular that it can help people find/discover
their package.  The same idea is behind the Elisp
libraries that are part of Emacs (modulo hysterical
raisins etc.)

Re: Naming guidelines for ELPA packages

[Madhu]

* Richard Stallman <E1pygTK-0004et-1U @fencepost.gnu.org> :
Wrote on Mon, 15 May 2023 18:15:14 -0400:

> The last paragraph of your draft text, about goblin-functions,
>
>   > Instead, I finally opt for a compromise: I'll still use "Goblin"
>   > when documenting the package and prefix names in my code with
>   > "goblin-", but I decide to submit it to GNU ELPA as
>   > "goblin-functions". While this isn't as descriptive as "gobject",
>   > it does at least provide a hint to the reader that this is a
>   > collection of functions (intended for other Lisp authors, as
>   > opposed to end users).
>
> seems to do that -- so why is a change needed?
>
> I think goblin-gobjects might be a superior compromise.

In case you missed it, goblin-mode was the Oxford Dictionaries word of
the year for 2022, in what seems to rigged elections and an exercise of
social media engineering

https://apnews.com/article/europe-oxford-e1ce91a4c56588c5ece25353cbe52810

	LONDON (AP) — Asked to sum up 2022 in a word, the public has
	chosen a phrase.

	It defines the term as “a type of behavior which is
	unapologetically self-indulgent, lazy, slovenly, or greedy,
	typically in a way that rejects social norms or expectations.”

	First seen on Twitter in 2009, “goblin mode” gained popularity
	in 2022 as people around the world emerged uncertainly from
	pandemic lockdowns.

	“Given the year we’ve just experienced, ‘goblin mode’ resonates
	with all of us who are feeling a little overwhelmed at this
	point,” said Oxford Languages President Casper Grathwohl.

Re: Naming guidelines for ELPA packages

[Jim Porter]

On 5/14/2023 12:33 PM, Philip Kaludercic wrote:
> Jim Porter <jporterbugs@gmail.com> writes:
> 
>> I think I need to adjust the passage a bit to emphasize that the
>> Emacs/ELPA maintainers would *prefer* a simple and straightforward
>> name like "gobject". ...
> 
> That would sound acceptable to me.

Ok, how about something like the following? I just expanded it a bit to 
provide more context and adjusted the wording slightly here and there 
(for example, these are now "recommendations" instead of "guidelines").

----------------------------------------

Naming is hard. However, taking some time to choose a good name for your 
package will help make your package easier to find and to use. To assist 
package authors, here are some recommendations for choosing good Emacs 
package names. Package names should be:

   * Memorable: Aim for short, distinct names that users can easily recall.
   * Intuitive: Names don't need to fully describe a package, but they 
should at least provide a hint about what the package does.

For example, suppose I've written a package that provides an interface 
between GObjects and Emacs Lisp, and named it "goeli". This isn't a very 
good name, since it's not easy to remember (users may find themselves 
asking, "Wait... was it 'goli' or 'goeli'?"), and it's nearly impossible 
to guess what it does from the name.

After thinking about it some more, I have a flash of insight: I'll call 
it "goblin" (for _GOb_ject _L_isp _In_terface)! This is easy enough to 
remember, but it's still not intuitive.

Perhaps the best name for a package like this would simply be "gobject". 
That's both memorable *and* intuitive, not to mention being as 
straightforward as you can get. If possible, the ELPA maintainers 
recommend that you choose a name like this.

However, suppose that at this point, I find myself disappointed: while 
"gobject" is a thoroughly practical name, I just don't want to give up 
the name "goblin". Instead, I could opt for a compromise: I'll still use 
"Goblin" when documenting the package and prefix names in my code with 
"goblin-", but I decide to submit it to GNU ELPA as "goblin-gobject". 
While this isn't as concise as "gobject", it does let the user know 
right away that this package has something to do with GObjects.

Re: Naming guidelines for ELPA packages

[Akib Azmain Turja]

[-- Attachment #1: Type: text/plain, Size: 2829 bytes --]

Jim Porter <jporterbugs@gmail.com> writes:

> On 5/14/2023 12:33 PM, Philip Kaludercic wrote:
>> Jim Porter <jporterbugs@gmail.com> writes:
>> 
>>> I think I need to adjust the passage a bit to emphasize that the
>>> Emacs/ELPA maintainers would *prefer* a simple and straightforward
>>> name like "gobject". ...
>> That would sound acceptable to me.
>
> Ok, how about something like the following? I just expanded it a bit
> to provide more context and adjusted the wording slightly here and
> there (for example, these are now "recommendations" instead of
> "guidelines").
>
> ----------------------------------------
>
> Naming is hard. However, taking some time to choose a good name for
> your package will help make your package easier to find and to use. To
> assist package authors, here are some recommendations for choosing
> good Emacs package names. Package names should be:
>
>   * Memorable: Aim for short, distinct names that users can easily recall.
>   * Intuitive: Names don't need to fully describe a package, but they
>     should at least provide a hint about what the package does.
>
> For example, suppose I've written a package that provides an interface
> between GObjects and Emacs Lisp, and named it "goeli". This isn't a
> very good name, since it's not easy to remember (users may find
> themselves asking, "Wait... was it 'goli' or 'goeli'?"), and it's
> nearly impossible to guess what it does from the name.
>
> After thinking about it some more, I have a flash of insight: I'll
> call it "goblin" (for _GOb_ject _L_isp _In_terface)! This is easy
> enough to remember, but it's still not intuitive.
>
> Perhaps the best name for a package like this would simply be
> "gobject". That's both memorable *and* intuitive, not to mention being
> as straightforward as you can get. If possible, the ELPA maintainers
> recommend that you choose a name like this.
>
> However, suppose that at this point, I find myself disappointed: while
> "gobject" is a thoroughly practical name, I just don't want to give up
> the name "goblin". Instead, I could opt for a compromise: I'll still
> use "Goblin" when documenting the package and prefix names in my code
> with "goblin-", but I decide to submit it to GNU ELPA as
> "goblin-gobject". While this isn't as concise as "gobject", it does
> let the user know right away that this package has something to do
> with GObjects.
>

The example name you suggested, "gobject", is indeed a good name, but
there's a little problem that if someone ever comes up with a better
package, it won't find any name for itself.

-- 
Akib Azmain Turja, GPG key: 70018CE5819F17A3BBA666AFE74F0EFA922AE7F5
Fediverse: akib@hostux.social
Codeberg: akib
emailselfdefense.fsf.org | "Nothing can be secure without encryption."

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Naming guidelines for ELPA packages

[Philip Kaludercic]

Akib Azmain Turja <akib@disroot.org> writes:

> Jim Porter <jporterbugs@gmail.com> writes:
>
>> On 5/14/2023 12:33 PM, Philip Kaludercic wrote:
>>> Jim Porter <jporterbugs@gmail.com> writes:
>>> 
>>>> I think I need to adjust the passage a bit to emphasize that the
>>>> Emacs/ELPA maintainers would *prefer* a simple and straightforward
>>>> name like "gobject". ...
>>> That would sound acceptable to me.
>>
>> Ok, how about something like the following? I just expanded it a bit
>> to provide more context and adjusted the wording slightly here and
>> there (for example, these are now "recommendations" instead of
>> "guidelines").
>>
>> ----------------------------------------
>>
>> Naming is hard. However, taking some time to choose a good name for
>> your package will help make your package easier to find and to use. To
>> assist package authors, here are some recommendations for choosing
>> good Emacs package names. Package names should be:
>>
>>   * Memorable: Aim for short, distinct names that users can easily recall.
>>   * Intuitive: Names don't need to fully describe a package, but they
>>     should at least provide a hint about what the package does.
>>
>> For example, suppose I've written a package that provides an interface
>> between GObjects and Emacs Lisp, and named it "goeli". This isn't a
>> very good name, since it's not easy to remember (users may find
>> themselves asking, "Wait... was it 'goli' or 'goeli'?"), and it's
>> nearly impossible to guess what it does from the name.
>>
>> After thinking about it some more, I have a flash of insight: I'll
>> call it "goblin" (for _GOb_ject _L_isp _In_terface)! This is easy
>> enough to remember, but it's still not intuitive.
>>
>> Perhaps the best name for a package like this would simply be
>> "gobject". That's both memorable *and* intuitive, not to mention being
>> as straightforward as you can get. If possible, the ELPA maintainers
>> recommend that you choose a name like this.
>>
>> However, suppose that at this point, I find myself disappointed: while
>> "gobject" is a thoroughly practical name, I just don't want to give up
>> the name "goblin". Instead, I could opt for a compromise: I'll still
>> use "Goblin" when documenting the package and prefix names in my code
>> with "goblin-", but I decide to submit it to GNU ELPA as
>> "goblin-gobject". While this isn't as concise as "gobject", it does
>> let the user know right away that this package has something to do
>> with GObjects.
>>
>
> The example name you suggested, "gobject", is indeed a good name, but
> there's a little problem that if someone ever comes up with a better
> package, it won't find any name for itself.

One could argue this would help preventing NIH and encouraging people to
contribute to existing projects.

Re: Naming guidelines for ELPA packages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The example name you suggested, "gobject", is indeed a good name, but
  > there's a little problem that if someone ever comes up with a better
  > package, it won't find any name for itself.

I think there will be no great difficulty.  It could be `gobject-2'
or `gobj-susan' or many other things that would be somewhat good.

So I think Philip's recommendations are good.

  > One could argue this would help preventing NIH and encouraging people to
  >  contribute to existing projects.

If it has a little such effect, that could be beneficial.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)