The name "Archetype" is confusing

[evankanderson]

Anecdotal evidence: Many people (PM, Eng, UX) introduced to Archetype concept were confused at first.

We had ~15 people sitting in the UI design sprint and general sentiment was “What’s going on with this Archetype thing? Why does it have to be so weird? Why is it a thing at all?”. There is a desire to aim at hiding the concept of Archetype from new users in the UI and CLI -- this is not a good sign for intuitiveness of the concept. People use alternative names in the discussions -- also not a good sign for intuitiveness of the concept and of the name.

[evankanderson]

The main motivation for Archetype is to enable a single jumping-off point for future updates which is friendly to both human and machine edits. It's assumed that "edit" will be the most common/frequent use case, but some use cases may call for "replace", instead.

I wrote up a substantial (drawings and everything) explanation. For comment access to the doc, see the link at the bottom.

[evankanderson]

Possible suggestions:

• HeadRevision
• Head
• Model
• RevisionModel
• RevisionTemplate (an earlier name rejected due to confusion with the field in spec)
• RevisionTrack
• RevisionSpec (perhaps even more confusing than RevisionTemplate?)

[evankanderson]

Note: the name is particularly confusing to non-native speakers.

[mikehelmick]

HeadRevision doesn't seem correct, as it isn't the head revision, but rather the configuration for generating the head revision.

Something along the lines of Model seems most appropriate. RevisionModel is fine if we think that Model is simply too generic.

[dewitt]

If this type is going to be used to implicitly generate a Service (for 1:1), and explicitly generate Revisions, then how about Source? I think we need something the user really identifies with if it's perhaps the only thing they see. The payload works for this as well.

[evankanderson]

A few other options:

• Settings
• Configuration
• Base
• Prototype (calls out to Javascript, might be a plus or a minus)

[mikehelmick]

I like Prototype as well. Prototype is a common programming construct, and should be familiar to developers. Yes, more common in Javascript, I don't think that is a minus.

@steren @qelo - What do you think of Prototype from a usability standpoint?

[qelo]

I quite like Prototype and Base.

Are we very motivated to have a single word? Like Archetype/Model/Prototype/Base, as opposed to RevisionBase, RevisionPrototype, ServicePrototype, ServiceModel etc? I think aiming for single word is contributing to the confusion, because these single words feel very generic and underspecified. Especially when there are more primitives in Elafros, it's becoming unclear what these single words refer to, is it a prototype for a service, for a revision, or maybe prototype for a Router/TrafficSplit, or maybe something else? A name like RevisionBase is more specific and in consequence less controversial, I think.

Unless we want to rename Service->Router and Archetype->Service, as suggested in #63 . My single word criticism above applies to 'Service' much less, as it's not as generic and underspecified as Prototype/Base/Settings/Archetype etc. Except Service here is not serving anything by itself, quite weird..

Currently these are my favorites:

1. Service + RevisionBase + Revision
2. Service + RevisionPrototype + Revision

I would be quite comfortable showing "Revision Base" in the UI if I had to, I already have "List of revisions" etc, it doesn't feel as detached as Archetype.

[steren]

I agree that Base and Prototype feel less cryptic.
I also would like to add the 'Revision' suffix, to make it clearer what it is for

So my preference also goes for:

1. Service + RevisionBase + Revision
2. Service + RevisionPrototype + Revision

[jurekPapiorek]

Other options mentioned in the comments on the api draft was:

• Stream
• RevisionStream

I find it most intuitive to have a Revision{Stream,Track,Train} object that inside has a named subobject called "headRevision". I.e. we should highlight the "grouping related Revisions" aspect of the Archetype in the name, rather than the "stamping out" aspect.

When I have a service that splits traffic across a number of various builds created by separate CI/CD pipelines, I'd call it "my service splits traffic across a number of revision streams" rather than "across a number of revision prototypes".

[evankanderson]

@dewitt has a better writeup coming shortly, but I thought I'd explain a bit more (from something I wrote up in a 1:1 conversation and forgot about) about the intent of the resource currently known as Archetype/RevisionTemplate:

1. Archetype should be viewed as the current desired state of the deployment. Assuming you're bought into https://12factor.net/, the Archetype helps to solve the following problems:
   II. Dependencies: Explicitly declare and isolate dependencies
   III. Config: Store config in the environment
   IV. Backing services: Treat backing services as attached resources
   V. Build, release, run: Strictly separate build and run stages
   X. Dev/Prod parity: Keep development, staging, and production as similar as possible.

Archetype provides a "platonic ideal" of the current status of the a particular deployment such that new releases can re-use the existing dependency, config, and service information, and changes to that information can be "versioned" in separate, parallel track to the code revisions in source control are versioned. In the current API draft, this is done primarily through environment variables, but in the future, I'd expect Open Service Broker bindings to be another set of properties on the Archetype, with the same results -- changing a binding would cause a new Revision to be created. (We don't have this integrated, because the OSB story is still moving and the language/runtime integration is not nailed down.)

Note that it's impossible to "run" an Archetype; the Archetype exists as a "north star" that the Revisions (which are things that actually run code, scale, etc) steer towards. We have a bit of syntactic sugar in the ElaService (which probably also deserves a better name) which allows the common case of "I want the latest working thing" to refer to the most recent Revision which was able to start via ElaService.spec.traffic.archetypeName/Archetype.status.latestReadyRevisionName.

2. Revisions should be immutable in the 12-factor sense; I'd expect that the underlying libraries and base image would all be immutable[2] and baked into the container image. At some point, Google or third-parties may provide various mechanisms to create (and roll out?) new Revisions to address security vulnerabilities, which might do a re-build of the source with newer dependencies. The unit of immutability of the runtime would be the container image (and, in fact, the Prime compute component would only be concerned about running containers). I'd expect kernel and CPU would be mutable (and under the control of the cluster admin, rather than the deployer), and there would be a (versioned) runtime contract about what the container might expect.

[cooperneil]

Other naming suggestions by @evankanderson and @dewitt, proposed in issue #63
ElaService --> Route
Archetype --> Configuration

[evankanderson]

It's been brought up (in person) that the ElaService name doesn't exactly roll off the tongue, and that Service is already a k8s concept which is related but different from what ElaService encompasses.

Service is a named abstraction of software service (for example, mysql) consisting of local port (for example 3306) that the proxy listens on, and the selector that determines which pods will answer requests sent through the proxy.

ElaService also provides a "named abstraction of a software service", but is explicitly an HTTPS L7 concept dispatched via the Host header, rather than a network TCP port. Additionally, it determines which Revisions will receive traffic, rather than concrete Pods. (A Revision may be materialized on zero pods when a request is received by ElaService, which would trigger 0->1 scaling.)

As such, it's probably prudent to rename both ElaService (an awkward "I want to be" name) and Archetype at the same time. The current best suggestion I've heard is s/ElaService/Route/, s/RevisionTemplate/Archetype/, and s/Archetype/Configuration/ (since the Archetype concept is really a declarative specification of the desired service configuration). We can then use the term "service" (lowercase, not a resource type) to refer to the constellation of Route, Configuration(s) and Revisions which provide a named abstraction of a software service.

I'll try to put together a PR tonight for this, though I'll hold it open until people have had a chance to comment/suggest better names. I've often found that having a concrete proposal helps to inspire even better names, and I'm hoping that will happen here.

[steren]

Regarding Archetype:
When detailing use cases to justify the use of Archetypes (#102 (comment)), the word "Track" or "Revision Track" was used. This is a term we already listed before #65 (comment).

Personally, I like "Configuration" too, as this is how I have been seeing Archetypes before: they are just server-side templates users can use to create new revisions.

[steren]

Regarding renaming ElaService (#65 (comment))

We can then use the term "service" (lowercase, not a resource type) to refer to the constellation of Route, Configuration(s) and Revisions which provide a named abstraction of a software service.

I think this sentence is key. Tools that users manipulate still need to be able to talk about "services", as we know from user studies that this is a term used by our users. Developers use Ela to implement "micro-services" architectures.

Q: How do you name the compute pieces of your architecture

[mchmarny]

Capturing decision from today's sync on this:

We have consensus on Route and Configuration as new names

Will close this issue when PR with these changes is committed to master.

[mattmoor]

@vaikas-google @evankanderson Who wants to do the honors? I'm happy to, if it means closing this :D

[evankanderson]

I was starting to do this last night when my son woke up; I'm happy to put together a PR monday at the latest, but if you want to do the sed, I won't stop you.

Note that this is going to make all the existing clusters sad, so we should probably do a big announcement when we land the PR. (Or check it in Friday night and go skiing all weekend...)

[vaikas]

I can do this today. I'll send out a PR later today.

…

On Fri, Feb 9, 2018 at 11:41 AM Evan Anderson ***@***.***> wrote: I was starting to do this last night when my son woke up; I'm happy to put together a PR monday at the latest, but if you want to do the sed, I won't stop you. Note that this is going to make all the existing clusters sad, so we should probably do a big announcement when we land the PR. (Or check it in Friday night and go skiing all weekend...) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#65 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AKwedFy1v-m6bzMRddi8owGc9MO56KJ1ks5tTJ9VgaJpZM4R3-Jo> .

[evankanderson]

Re: steren's comment

Tools that users manipulate still need to be able to talk about "services", as we know from user studies that this is a term used by our users. Developers use Ela to implement "micro-services" architectures.

I agree that "Service" (and "Application") are important terms. I'm slightly happier not using those terms for any of the tools we provide, so that customers can use our tools in interesting ways to build what they think of as a "Service". An example where I think the new names help:

Let's say that I'm using serverless function composition to mash up pictures (selfies). I may think of that operation as my "Service", but it's built as three interlocking Routes + Configurations (two of which are generic library containers:

I think of the green thing as my "service", so it's nice that we're not making me call some part of that "service" or "application".

[mchmarny]

@vaikas-google when this PR lands we will also need to update samples. Worth making this all into one PR?

[vaikas]

Was planning on it, yes 👍

[vaikas]

renames are done and samples run.