[tor-dev] Standardizing the 'onion service' name

Thu Apr 26 16:27:35 UTC 2018

Thanks teor for spelling things out in moderate detail and Steph for
commenting.  

My tl;dr is to basically concur with everything they both said:  The
further from user-facing and the more embedded down in the codebase,
variables, code comments, controller commands, etc. the less important
to spend effort eliminating such vestiges from existing text. Going
forward, certainly any code comments and e.g. any commands that won't
break things should use current terminology.

aloha,
Paul

On Thu, Apr 26, 2018 at 11:07:27AM -0400, Stephanie A. Whited wrote:
> Hi!
> 
> Thanks for adding me to the thread.
> 
> 
> On 4/26/18 3:34 AM, teor wrote:
> > Hi All,
> >
> > There seems to be some confusion in this thread about the
> > current state of the hidden service to onion service name transition.
> >
> > So I'm going to describe the state of things as they are, then try to
> > describe what would need to be done.
> >
> > I'd also appreciate feedback from Steph and others on our priorities for
> > transitioning to the onion service name. I think we have been prioritising
> > user-facing text. (The blog, website, Tor Browser, metrics,  etc.)
> Yes, user, funder, and press facing text has consistently been using
> onion services at least since I've been on board. When I first joined,
> the message to me was that this was changed a couple years prior but
> changeover had been slow. I realize now a lot of folks didn't get that
> message.
> 
> We have already, with the help of Kat, updated hidden to onion services
> where possible on the website. I think the exception to this is older
> blog posts.
> 
> I realize it is not as easy to change some of the other elements, like
> the directory protocol, but I think it's important to make what changes
> are possible. I think it'd have a very positive impact to see these
> through.
> 
> Being aligned will help us build trust with the press, new users, etc.
> There are several reasons the name changed, if it is helpful to share
> more about that lmk.
> 
> >
> > Is this a sensible way of prioritising things?
> >
> > On 26 Apr 2018, at 16:42, Paul Syverson <paul.syverson at nrl.navy.mil
> > <mailto:paul.syverson at nrl.navy.mil>> wrote:
> >
> >>> Have OnionService aliases for controller commands, events, 
> >
> > These are current called "hidden service" or an abbreviation.
> >
> > Tor could add an alias mechanism for controller commands, events,
> > and fields, and use it to do the rename:
> >
> > https://trac.torproject.org/projects/tor/ticket/25922
> > <https://trac.torproject.org/projects/tor/ticket/25922#ticket>
> >
> > I don't think they are as high a priority as the torrc options and man
> > page.
> >
> >>> descriptor
> >>> fields
> >
> > These are currently called "hidden service", or an abbreviation.
> >
> > Descriptor fields are part of the directory specification and
> > implementation, and they are highly technical. So I'm not sure we gain
> > much from aliasing them or renaming them.
> >
> > Similar arguments might apply to other codebases:
> > * Onionoo
> > * stem
> > * consensus health
> > * Tor (network daemon)
> >
> > But the following user-facing applications should add documentation or
> > change names, if they haven't already:
> > * Relay Search / metrics website
> >   * uses HSDir for relay search, because that's what it's called in the
> >     directory protocol
> >   * uses "onion service" for statistics
> > * Tor Browser
> >   * uses "onion site"
> > * the Tor website
> > * new tor blog posts
> Website and new posts are covered.
> >
> >>> and anything else referencing 'HS' or 'HiddenService'.
> >
> > We considered adding OnionService* torrc option aliases for every
> > HiddenService* option in 0.2.9. But we deferred that change because we
> > ran out of time.
> >
> > All we need to do is add some new entries in the alias table, then do a
> > search and replace in the tor man page:
> > https://trac.torproject.org/projects/tor/ticket/17343
> >
> >>> Speaking of which, how do we plan to replace abbreviations? Having an
> >>> 'OSFETCH' or 'OS_CREATED' event doesn't exactly have the same ring as
> >>> their HS counterparts. ;P
> >
> > That's a good question.
> >
> > OS conflicts with "operating system", so we could use:
> > * Onion
> > * OnSrv
> > * no abbreviations
> > Or any other colour you want to paint the bikeshed.
> >
> > To avoid an endless discussion, let's leave the decision to
> > the people who write, review, and merge the code.
> >
> >>> Adjust all our docs to be consistent about the name.
> >>
> >> Right, anything v3 should be consistently calling these 'onion
> >> services'.  Variable names, etc. particularly those still in use in
> >> code shared with v2, don't need to be changed. It is OK if such
> >> vestiges of older usage remain in abbreviations, as long as the
> >> description of them, e.g., in any new Tor proposal, describes them
> >> with appropriately current terminology.
> >
> > torrc options, the tor man page, and the v3 onion service code
> > mainly use "hidden service", and sometimes use "onion service".
> >
> > I don't see much value in changing the code.
> >
> > If we decide there is value in changing the torrc options and man page,
> > we need to allocate a few days of work on the roadmap to make it
> > happen.
> >
> >>> Renaming takes work. Lesson I learned from Nyx is that it works best
> >>> if you draw a line in the sand and stand by it. With Nyx, version 2.0
> >>> is called Nyx (you won't find any docs saying otherwise) and version
> >>> 1.x is the legacy 'arm' project.
> >>>
> >>> If I was in your shoes I'd opt for the same. Either prioritize the
> >>> aliases and be firm that v3 are 'Onion Services' or abort the rename.
> >>> Otherwise this will live in a confusing dual-named limbo land
> >>> indefinitely. ;P
> >>
> >> I'm prettty sure that v3 being 'onion services' has been the official
> >> Tor Project position since at least half a year. We wouldn't be
> >> aborting the rename, because 'abort' would imply it is not
> >> complete. Anything now not using the current name is not part of an
> >> incomplete process, it is simply wrong and outdated. Steph correct me
> >> if I am wrong about that.
> >>
> >> So I think you've answered your own question. Nothing in v3 should be
> >> called 'hidden services'.
> Right. In our communications, all are onion services, there are just
> different versions and configurations possible.
> 
> If I've missed something I can respond to more specifically in this
> thread, please lmk.
> -Steph
> >
> > That's not the current state of the tor network daemon v3 onion service
> > code, specs, options, and man page. They use a mix of terminology
> > (see above).
> >
> >> And anything new in code and documentation
> >> should be called 'onion services'. If you want to think of v2 and
> >> earlier as 'hidden services' for purposes of understanding legacy
> >> component and variable names, e.g., HSDir that's fine. And as such,
> >> variable names, etc. in code that continues to be used for both v2 and
> >> v3 can can persist. But again, any new specs, documentation, etc.
> >> should call them 'onion services'.
> >
> > We have gradually been using onion services in new documentation and
> > specs, since "single onion services". But we haven't changed existing
> > code and documentation.
> >
> >> This acceptance of existing v2 documentation calling them 'hidden
> >> services' while refusing this for anything v3 is a little misleading
> >> about when and why the naming transition happened, but its close
> >> enough to serve as your line in the sand if you feel one is needed.
> >> I actually argued the value of essentially such a line-in-the-sand
> >> position to Steph a while ago. This doesn't preclude also calling v2
> >> and earlier 'onion services'. Indeed, it's not just OK but preferable,
> >> for the above mentioned reasons.
> >
> > It looks like we are doing a gradual transition. I think we prioritised
> > the things that are seen by the most users (Tor Browser, statistics,
> > blog, website).
> >
> > We did not take a line in the sand position in the past, but we could
> > adopt one for the remaining changes. We could decide on a particular
> > Tor release (and releases of other codebases). But we need to schedule
> > the work on the relevant roadmaps.
> >
> > And maybe there are some obscure technical things (code, comments,
> > descriptor fields) that just aren't worth changing.
> >
> > T
> 