Opened 3 years ago

Closed 22 months ago

#19616 closed enhancement (fixed)

Consider renaming metrics-lib

Reported by: iwakeh Owned by: metrics-team
Priority: Medium Milestone: metrics-lib 3.0.0
Component: Metrics/Library Version:
Severity: Normal Keywords: metrics-2018
Cc: atagar Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

applies to

  • git
  • trac
  • documentation
  • where else?

Child Tickets

Change History (21)

comment:1 Changed 3 years ago by karsten

Cc: atagar added

I admit that we're already in the middle of the renaming process, but let's consider atagar's concerns from #19398 before moving forward here:

I still really dislike the 'DescripTor' name. metrics-lib is a lot less confusing. The word 'Descriptor' already has a meaning and it's not this.

A few arguments in favor of the renaming are that we have been using metrics-lib and DescripTor interchangeably since the very beginning (org.torproject.descriptor), that the main purpose of this library is to process Tor descriptors, and that the name DescripTor fits well into related projects like CollecTor and maybe ExoneraTor.

But I understand that atagar is the native speaker here and also a survivor of renaming his "arm" tool to "nyx". atagar, can you add more thoughts to this discussion to explain why you dislike the name DescripTor so much?

comment:2 Changed 3 years ago by atagar

Certainly. The trouble with DescripTor is that it's the same noun as the thing both it and other things process. I know you like embedding the word "tor" within your projects (despite Roger advising against it), but unlike ExperimenTor, DocTor, and CollecTor the name 'DescripTor' causes confusion every time the name is spoken.

Try the sentence "Drats, that's a DocTor issue". That sentence makes sense because we don't have a bunch of doctors involved with Tor so it must mean the DocTor service. If you try say "Drats, that's a descriptor issue" it's ambiguous if you mean a descriptor or DescripTor.

Imagine for instance if I decided to rename Stem to ToR. Technically the case of the letters is different from Tor but it would none the less be a source of endless confusion. :)

comment:3 Changed 3 years ago by atagar

TL;DR: Trouble is the name collision with a term commonly used in our space. If you chose 'VecTor', 'SculpTor', or any other word not commonly used in our space this wouldn't be an issue. For ideas that keep your convention check 'grep "tor$" /usr/share/dict/words' - there's 1,595 options.

The trouble with 'DescripTor' is actually the same issue I ran into with 'arm'. Confusion with the body part wasn't an issue, but the processor *was*. Any time 'arm' was discussed in #tor-dev it caused a moment of confusion where nobody knew which we were discussing.

comment:4 Changed 3 years ago by iwakeh

@atagar: Your concerns are all more than valid. Thanks for pointing this out!

Brainstorming for new names:

Someone/something that reads/processes documents is an EdiTor or LecTor.
These would be shorter than 'descriptor'. But of course there are tons of editors around.

Looking at the definition by Merriam Webster:

Lector , n. (Eccl.) A reader of lections; formerly, a person designated to read lessons to the illiterate.

For the $java-tor-descriptor-parsing-library:

LecTor helps those that would otherwise not be able to read/process descriptors (using java).

Regarding the Change

We are aiming at a major change with release 2.0 and java 8 and removal of deprecated methods.
And I think we're at a point were such a renaming is still doable.

comment:5 Changed 3 years ago by iwakeh

Summary: metrics-lib should be renamed to DescripTormetrics-lib should be renamed

In our meeting (a few seconds ago) we decided that LecTor could be a fine name.

Is that a reasonable name for the $java-tor-descriptor-parsing-library (aka: metrics-lib)?

comment:6 Changed 3 years ago by atagar

No objections from me. Don't have a strong feeling on that name either way. :)

Thanks!

comment:7 Changed 3 years ago by iwakeh

Milestone: metrics-lib 2.0.0

comment:8 Changed 3 years ago by karsten

Summary: metrics-lib should be renamedConsider renaming metrics-lib
Type: taskenhancement

comment:9 Changed 2 years ago by karsten

Milestone: metrics-lib 2.0.0

While I see the benefit of doing the renaming before putting out 2.0.0, I don't think we're ready to pick a new name at this point. When we rename metrics-lib, we should considering doing the same with the other metrics-related tools. What we should avoid is rename metrics-lib now and then once again six or twelve months later. But on the other hand the plan to rename metrics-lib shouldn't block the 2.0.0 release, so I'm removing that milestone.

My suggestion is that we keep the two names metrics-lib and DescripTor for the moment and use either both or just metrics-lib name whenever we have the choice. We should not, however, change explicit mentions of DescripTor to metrics-lib. For example, we're using the name DescripTor for releases and for .jar files, and we should keep doing that. But when we announce 2.0.0 in a blog post of some sort we could prefer the name metrics-lib and only mention very briefly that it's also known under the name DescripTor, so that people downloading the release won't be too confused.

Oh well, sometimes writing code is easier than writing about code.

comment:10 Changed 2 years ago by iwakeh

Milestone: metrics-lib 2.0.0

comment:11 Changed 2 years ago by karsten

As indicated at last week's team meeting: how about we simply drop the name "DescripTor" and keep the "metrics-lib" part, rather than replace it with an entirely new name? More precisely, how about we call it "(the) Tor Metrics Library" in the long version (documentation, tutorials) and "metrics-lib" in the short version (Trac component, Git repository)? The renaming seems relatively easy to do when there are no open branches (because of having to rename org.torproject.descriptor to org.torproject.metrics.lib). How does this sound?

comment:12 Changed 2 years ago by iwakeh

I agree, metrics-lib should be the one name. DescripTor is too general.

Regarding the package name the 'standard' suggests turning the hyphen into an underscore, which would result in org.torproject.metrics_lib. A package name that is cumbersome to type and looks odd.
The additional sub-package lib is also not ideal; especially as there are org.torproject.onionoo and org.torproject.collector etc.
What about simply choosing org.torproject.metricslib or even the very short org.torproject.ml?
Other suggestions?

comment:13 Changed 2 years ago by karsten

Ah, I didn't explain my idea of using org.torproject.metrics.lib very well. I feel we're in the process of moving currently separate Metrics subprojects like CollecTor and Onionoo back to Tor Metrics. We already started doing that by moving their specifications to the Tor Metrics website (which we'll need to continue in July). And we put metrics-lib on the Tor Metrics website as well, making it part of Metrics rather than a single entity. That's why I implicitly assumed (sorry) that we'll pick a common naming scheme for packages, too. We already use org.torproject.metrics.web for the website part of metrics-web, so picking org.torproject.metrics.lib seemed logical. We'd have to rename a few more packages in metrics-web, Onionoo, and so on, but that can happen after we rename packages in metrics-lib. Another reason is that we could say that we "control" org.torproject.metric as Tor Metrics team and put all our code bases under that. All in all, I think I prefer org.torproject.metrics.lib from all suggestions above. Except there are downsides I didn't see?

comment:14 Changed 2 years ago by karsten

We'll need to make a decision here. We can postpone the actual renaming until putting out the release, but we should not delay the discussion until then. What do you think about my previous comment?

comment:15 Changed 2 years ago by iwakeh

I'll prefer shorter package names and we mailed/talked about renaming org.torproject.metrics.web to org.torproject.analytics.

But, I don't feel too strongly about his topic.

comment:16 Changed 2 years ago by iwakeh

Milestone: metrics-lib 2.0.0metrics-lib 3.0.0

renaming is a huge task -> postponed to the next major release.

comment:17 Changed 2 years ago by karsten

Milestone: metrics-lib 3.0.0metrics-lib 2.0.0

Hang on, we did postpone the package renaming part, but we said we'd still take out mentions of "DescripTor" from documentation parts and instead use "(the) Tor Metrics Library" (long form) or "metrics-lib" (short form) everywhere. Moving back to the 2.0.0 milestone, except for the package renaming part which will remain for 3.0.0.

comment:18 Changed 2 years ago by karsten

Milestone: metrics-lib 2.0.0metrics-lib 3.0.0

Ah, looks like #22732 covers those non-package parts. Moving back to 3.0.0.

comment:19 Changed 2 years ago by karsten

Owner: changed from karsten to metrics-team
Status: newassigned

Handing over to metrics-team, because I'm not currently working on this.

comment:20 Changed 2 years ago by karsten

Keywords: metrics-2018 added

comment:21 Changed 22 months ago by karsten

Resolution: fixed
Status: assignedclosed

The package renaming will now be part of #24028. Closing.

Note: See TracTickets for help on using tickets.