The Great Rename

Making Speckle Changelog
1

Hey @Community!

We are renaming the core concepts in Speckle to be more widely understandable - in a backwards-compatible manner and with a graceful migration path forward.

Naming Things is Hard

Speckle started as a geeky product: as hackers in the AEC industry we wanted to scratch our own itches. Why did it have to be so complicated to share models with others, view them online, or query BIM data? Speckle was born as the answer: a fast by default object based data platform for AEC, where diffing just happens and each atom of your model is versioned and tracked. And, of course, open source - because, as developers, we want to be in control—and you do too.

Despite Speckle’s geekiness, we saw the community quickly grasp its complexity and put it to good use. Nevertheless, we have now reached a turning point: even Dim’s dad (in his late 60s), an architect refusing to retire and SketchUp modeller, is now using Speckle. Our audience is now much wider than at the start!

When we hit the ground with Speckle 2.0, “commits” felt like the way to indicate snapshots in time of models. Branches - geek alert - are, obviously, collections of commits. Naturally, they are grouped inside “Streams”, which in Speckle-land are the equivalent of a repository. Everybody gets it, right? Eh… right?

The feedback from our community, partners and customers was unanimous: you get it, but your colleagues don’t. It takes ages to explain Speckle, and the existing concepts do not stick. So here’s what we’re going to do:

  • Streams will be renamed to Projects
  • Branches will be renamed to Models
  • Commits will be renamed to Versions

The structure stays the same. Projects contain multiple Models, and each model can contain multiple Versions.

great-rename-doc
great-rename-doc1000×433 36.5 KB

Backwards Compatibility & Forward Future

For the more technical minds, we know what you’re thinking: will I have to change my scripts and code? Well, we’re developers too. We hate when APIs change without warning - so the answer is no. We simply flag endpoints as deprecated, but we will keep them around for a long time. Theoretically, we can keep them around forever, but we hope we won’t need to do that.

You also might be wondering if we are sneaking in other changes. The answer is yes—we are changing some ways things behave: models can now be infinitely nested, for example. Comments are now accessible throughout all the versions of a model. Nevertheless, all these changes live under new GraphQL API routes that do not conflict with the old ones.

Incoming Product Changes

We’re talking a lot about API changes, but how does that impact the Speckle that you see and use? Well, the renaming operation isn’t just a “find and replace” exercise throughout the codebase. It’s driven by product and user needs which manifest as two current initiatives: FE2 and DUI3.

FE2 stands for Frontend 2, and DUI3 stands for Desktop User Interface 3 (versioning is also hard, but that’s a different story). DUI3 is in early stages of development, but FE2 is now available on our testing server and is a complete paradigm shift from the old web app. It’s designed around the concepts of Projects, Models, and Versions and is much more approachable for old and new users alike.

20 Likes
2

Something I loved about Speckle was that you were encouraging a change in language within the industry to use of source control terms from programming.

3

Oh, now it is so much clearer even to me, a 90% geek 10% engineer :smiley:
It always felt that the SCM terms were a bit of a stretch, since most of the common git workflows/operations were not really applicable.
Now I get that branches/models were not really meant to hold variants of the same information to be diffed and merged, but they hold different aspects of the same project.
Also, now that the terminology is more familiar to my colleagues, I could finally convince them to try it (I’ve put up a server instance a year ago but the only stream there in my test :rofl: )

Keep up the good work!

8 Likes
4

I also have same problem before when explain for engineer and some leaders understand about what is stream, branch, commit, base, … But some of them still blur about that. Luckily, Speckle team had done it now, cheer :wink:

7 Likes
5

We just want to speak the language most of our users understand. @Wilfred I hope your love of Speckle will last :heart_decoration: :speckle:

5 Likes
6

Mos def a great change! I’ve passed this around to geeks, designers, and devs and we all agree this is much clearer.

:100: agree! And I think if it was completely structured like git it might cause more resistance with AEC adoption. I think these changes will help designers and devs continue to unpack the ways they can make speckle work and grow to best fit both parties :balloon:

3 Likes
7

bump? I assumed this was imminent when it was announced.

8

You sound disappointed @StephenC, what are you most looking forward to seeing?

We are trying to develop as openly as possible while balancing moving quickly with getting things right. The number of Speckle users is now hugely more than the at evolution from Speckle v1 > v2, hence:

  • early announcements of breaking changes for teams such as yours to amend internal change management and operating models,

  • releasing for public testing the next generation frontend where all the new terminology is in place.

  • inviting Speckle community to UX 1:1 usability sessions to explore feedback on how we’ve gone beyond just renaming but also improving functionality on both FE2 & DUI3 the next generation of Connectors UI.

  • working on the updates to all our docs and tutorials so that when the switch happens, it’s as least confusing as possible.

  • wherever possible evolving our language in responses here on the forum; Project Streams, Model Branches and Version Commits; such that future community searches should remain relevant.

Have you signed up to these initiatives? Let us know if your team needs more from ours.

2 Likes
9

3 posts were split to a new topic: Token issue with FE2

10

What do we actually call commit messages since the great rename?
Version commit message?
Version upload message?
Version upload note?
Version description?

Is there a name for this already?

11

Version message is the basic answer.

Do you have a preference?

1 Like
12

No, “version message” is actually fine for me, as long as it’ll be used consistently.

I guess I just felt like the word “message” is something that’s sent somewhere, which commits are when you push them to the remote or when you pull commits it makes sense to me that you receive messages. Whereas, I guess that, in my mind, “messages” doesn’t really make sense (yet), because my mind (for now) associates versions with these files that are stored in some folder somewhere with horrific suffixes.
I think I can get used to version message.

1 Like
13

We’re in the throws of documentation of FE2 now, so it is a timely thought.

  • As an API endpoint, it made sense to leave it as a message
  • As a UI feature in FE2, it doesn’t have a field title it is simply displayed in the versions list
  • As a UI in connectors, there is a field label which remains “message” for now

The message seems a good fit because we have seen people use this field for communicating purposes. As a factual data point, “75 elements from Revit”, maybe other nouns would fit better.

This is why we will be doing this much more as we consolidate all of our descriptions, as FE2 is poised to be the de facto default.

2 Likes