Naming, Terminology and Understanding all the New Awesomeness that is Revolution

Quote from: rickj at Oct 03, 2008, 05:19 PM

How about $modx->lang? Or is language technically incorrect in this context?
Edit: Ok, lang won’t work thanks for the clarification above.

Correct. We spent quite a bit of time early on in the i18n implementation of Revo discussing how those strings would be referenced. In 0.9.6, they were referenced by their language. We realized this simply wouldn’t work in Revo, and was painfully slow in 0.9.6 because it required every language string in that language to be loaded.

So, we decided to group lexicon entries (language strings) by how they were used. We created modNamespace as way of grouping them by their package (with ’core’ being the default). So that way, 3rd Party Package developers could have all their lexicon strings completely isolated from Revo’s core strings.

Then, we took it one step further. We created ’Foci’ (which we are now calling ’Topics’), which separated those lexicon strings into groups according to what section of the manager they were used in. All the chunk-related strings went into a chunk Topic, and that way the manager had to only load the strings for the topics it needed. This reduced the load times by nearly threefold.

Quote from: rthrash at Oct 03, 2008, 05:26 PM

So a vehicle only contains one thing, but might also be accompanied by a bundle of associated things that tell the thing that moves them around what to do with the vehicle contents?

But you’re completely missing the point of objectivity and primacy. A bundle implies there are things of equal - or similar - worth packaged together in a pack. That’s not the case. Validators and Resolvers are not in any way equal in primacy to the object in the vehicle; they rely on that object to even function.

There is only one primary object in a vehicle, and the other things in it are dependent on the object itself (or, in a file vehicle, the files).

Does the single vehicle item have any value of itself or must it always be accompanied by resolvers/validators?

No, a vehicle doesn’t need resolvers/validators. But a vehicle cannot have only validators/resolvers - it must have an object.

I could see a dev new to the Revo platform saying without any effort involved, "So their take on a container/bundle is just like product X, only much more capable." It’s something they’re likely and comfortable with, a term they’re used to using in the context of software.

No, they’d say, "So that package is just like product X."

I really honestly think you’re confusing Packages with Vehicles, and confusing yourself even further by trying to extend the metaphor too far.

What if we never had the privilege of having Bob working in our community because we’re presenting things that could be expressed more simply?

What if? What if? BobRay got through Template Variables. I’m pretty sure he’s smart enough to figure out Vehicles. Let’s not go into "what ifs"...those are emotionally manipulative at best, and provide no solutions, only complaints.

I really think you’re just confusing your own definitions of things rather than going by the ones we’ve provided. Packages are the central element. They contain vehicles. Vehicles hold an object that can have resolvers/validators. All packages can be installed via Providers, and put in your workspace.

But you’re completely missing the point of objectivity and primacy. A bundle implies there are things of equal - or similar - worth packaged together in a pack

I don’t ever view bundles as containing equally valuable or the same things at all. Sorry if it came across that way. Is that the common conception for most folks?

I really honestly think you’re confusing Packages with Vehicles, and confusing yourself even further by trying to extend the metaphor too far.

Isn’t that the point of this discussion: to learn what the heck all this means and to put it into a framework that each person can understand? I’m certainly not trying to get an emotional charge out of anyone, but I am learning through this repeated banging of the concepts into my head.

I do disagree on the value of asking "what if?" and think there’s considerable merit in posing hypothetical scenarios that don’t border on the ridiculous. How we frame everything is very important, and the example I used was directly related to what we’re discussing and came straight from Bob’s own words. I’m probably wrong, but he could have just as easily lumped us into the same bucket if we use less approachable language to describe the concepts in modx. If we go blindly down the path of accepting what’s mandated we wouldn’t have "topics" instead of "foci".

That’s NOT to say that the other terms must be changed, but there may be some merit in compromising. At the end of the day, I’m deferring to the guys doing the actual coding and architecture decide. Everyone deserves fair, honest, open-minded and deliberate consideration though. And not everyone will have the ability to get this immediately and will probably make some bad suggestions, too. Those are all OK and expected in my book!

If, and that’s a big "if", we can use more broadly approachable terms that both non-developers and that developers can understand with relative equal effort, and that accurately describe the concepts in Revo, then I think we win big. It might even give us two avenues to grow the developer user base that may ultimately become contributors to the code in general:

• Pull by attracting developers due to the technical functionality and capabilities in Revolution
• Push because less Jedi-like users are adopting modx (think of all the ad agency and design studio marketing sites being built) and developers not currently familiar with modx discovering that Revolution can do a heck of a lot more than just brochureware sites when then need a custom application to go along with a marketing site that’s already in place.

I really think you’re just confusing your own definitions of things rather than going by the ones we’ve provided. Packages are the central element. They contain vehicles. Vehicles hold an object that can have resolvers/validators. All packages can be installed via Providers, and put in your workspace.

I don’t know why the following couldn’t be just as easily said. It’s not as concise, but at least for me who wouldn’t recognize an object (yet!) if it bit me on the backside seems a bit more approachable:

The shorthand description of installing things into Revolution:
The Transport Packaging System installs Packages comprised of one or more wrapper Containers, each containing an Object and optionally Resolvers/Validators to make sure things are handled properly.

The more detailed explanation of how it all works:
In order to make it easy to distribute even complex collections of inter-related content, logic/code and/or data, these pieces are packaged together into Transport Packages. Packages can be installed with a single click inside the Manager by using the Transport Packaging System. Packages can be a single .zip file loaded through a dialog box, or installed remotely over the web from trusted Providers, such as the modx Web Transport Facility. All Packages are installed into a destination Workspace, which is typically your website.

Individual pieces inside a Transport Package are called Containers, with each Container containing the following:

• a primary object, like a piece of code, some data or a file,
• and optionally, Resolvers and Validators, which tell the Transport Packaging System where to place the object, how it relates to other Containers in the Package, and how to tell if it all went well.

Developers can include one or more Container in a Package using Developer-oriented build scripts. Using the Transport Packaging System it’s possible to bundle up entire sites or sections thereof—complete with all dependencies on the filesystem and data from the database being bundled up into a nice, neat, easily installable Package—for re-use, distribution or migration to elsewhere.

Wow, I sleep a little late and come in to find all this. I think it’s great.

I want to see if an idea will make Ryan’s metaphor work for him rather than against him.

First, remember that transport = package = transport package. It’s a key idea that I didn’t know, even though I’ve built and re-built several packages, so we should definitely do something about that.

Now, imagine a package as a vehicle ferry and it isn’t going to make the trip without at least one vehicle on board. It carries vehicles to their destination, which is exactly what a MODx package does. The captain of the ferry might have a "manifest" that described the order in which the vehicles should be unloaded and sent on their way.

Vehicles can carry things (which, in this case are modx objects like snippets and plugins) in the trunk. They can also carry passengers (yeah, I find I’m leaning back toward this).

In our case, passengers would come in at least three "types:"

validator -- these passengers check to make sure it’s ok to install the package
fileCarrier -- these passengers just carry files to install at the appropriate location
scriptCarrier -- these passengers carry a list of instructions (PHP script) to carry out when they reach their destination

Other types of passengers can be created as needed.

I don’t know if this makes sense to others, but it does to me.

PS: I’m not actually suggesting we change the name of package to "ferry."

Quote from: OpenGeek at Oct 03, 2008, 05:55 AM

BTW, I think VehicleValidator, etc. is redundant; when you are talking about Vehicles already anyway.

I have to disagree here, since we’re also talking about packages and transports and vehicleValidator makes it clear what the vehicle is attached to.

Nor is redundancy always a bad thing. In code design, it equals inefficiency, but in communication, it helps the receiver decode the message. In a user object, a variable called $userId is redundant, but helpful to whoever is reading the code.

And VehicleFileTransport is super redundant when a Vehicle is part of a Transport already. That would confuse me as a developer, to have Transports contain Vehicles and Vehicles containing more Transports as those terms imply.

Right. I forgot about the use of "transport" at the higher level (although it looks like we might be able to jettison it and just use "package)." That wouldn’t rule out fileCarrier, however.

If "passenger" doesn’t fly, my very close second choice would be:
Package
Vehicle
vehicleValidator
vehicleFileCarrier
vehicleScriptCarrier

Well, it seems that in this discussion, Vehicle/Container seem to be up for grabs.

However, as the core dev team, we’ll have to say we’re most likely to go with Vehicle, for these reasons:

• Container would cause problems with the 096 definition of container - resources that have children. This is a big issue.
• Container is just far too generic a term. It can mean anything, and only means what we’ve said here when explained in the context of packages and then explained how they relate.
• Changing all the classnames and code to reflect container would be a nightmare, and not worth it with regards to the ounce of benefit we may or may not get in changing it.
• I’ll repeat the 3rd point: a nightmare. It would require rewriting many parts of xPDO, and writing conversion scripts from prior Revo installs, as well.

With those in mind, we’ll most likely stick with Vehicle.

During the course of the discussion, I’ve come to like Vehicle, since the object carries things across the net to a destination. My main problem was with the lack of an obvious semantic relationship between "vehicle" and "resolver"  and the ambiguity of "resolver."

Sottwell suggests that the ambiguity is good because it does different things. It’s always a trade-off. You could have one giant object that does everything and call it "TheObject", or you could have a lot of tiny objects that each do one thing and give them appropriate names. 

In this case, I lean toward the latter only because of my complete inability to imagine what a resolver was or did when I first saw the term.  If I’m not alone in this, then "I understood it fine" isn’t a very strong counter-argument because people who say that will also understand a well-chosen replacement.

If it’s just me, then resolver is fine, since I now understand it. 

The challenge here is to convey all of the details of these features with as few words as possible. This is why I am so passionate about the names I’ve chosen for these things, because they were essential in designing the way they work.

Keep in mind, Resolvers, Validators, and Related Objects are specific to an xPDOVehicle, which is only one type of Vehicle which can be stored in a Transport Package. Other Vehicle classes may define their own payloads (the contents of the Vehicle) and how to deal with those payloads (implementation).

Well since we’re working on the information superhighway, I suppose Vehicle will work after all.

I’m getting my head around most of these terms. Expanding the Glossary of Terms will benefit many immensely and will be a foundation for the development docs for Revo. This thread is most helpful in the interim.

This is an honest question as I don’t have any answer or opinion but is it entirely necessary to have the terms of the elements match classes and functions/methods/objects in the core or could they not be assigned in the lexicon (a term that has grown on me) and be different in the manager and the API? They’ll only be the same in english any how so I wonder if they need to be tethered?

On another note, what do you all think about Workspaces being Package Manager or Package Management. I know that there will be future ability to assign different sets of packages to specific contexts but we could do something similar to the Topics as they relate to the Lexicon instead of separating by context. Or something like that.

Workspaces to me, while a friendly term has a nearly imperceptible relationship with packages etc. I think we can spare a few characters in the lexicon for that.

If "Workspaces" is tied into the core can it be decoupled or translated in the lexicon for users and otherwise refered to in the API. Again it will only matter to the English speaking devs all others will likely see different words to represent the term.

Thanks for everybody’s insight and keep teaching me.

Cheers,

Jay