Local Component Naming Conventions

[jmwright]

I've been dogfooding sliderule-cli, and it's (unsurprisingly) brought up a question. Should there be at least some best practices on local component naming to give an indication of where a component belonged/belongs? I'll give an example to help explain.

I've got an experimental project that's a 3D printed vacuum pump, which will end up being a mechanical assembly. I've created a "housing" component for the pump housing. If I refactor the housing component at some point, then there will be a remote component sitting somewhere with just the name "housing". There will presumably be a readme, but nothing in the name or any of the meta data indicates where that housing originally belonged (3D printed vacuum pump project). Once a component has been refactored, I don't see a way to trace its origin.

Questions:

• Am I correct about the lack of traceability?
• If I am correct, does it even matter?
• If it matters, what's the best way to provide some traceability?

[cypris]

If I'm correct, it doesn't matter, because it'll be in the repo history. If you want to know, you just look at the tree for the file, go back to when it was moved/renamed, and look at the state of the repository then if need be.

[m30-jrs]

Finally getting around to looking at this issue.

So, I think the heart of the issue is a question of encapsulation. On of the as yet unwritten user stories that is floating around my head has to do with slip-streaming component assembly instructions into the assembly instructions of the generated assembly instructions.

Presumably, the reason to refactor the housing in your example @jmwright is to support reuse (by yourself or others), so we are talking about a useful housing. Imagine the component ends up inside three different projects.

• vacuum pump
• air compressor
• air quality sensor (just roll with it)

We need to ensure that no vacuum pump specific details leak into the generated documentation (BoM reports, assembly instructions) for the air compressor or air quality sensor. Otherwise a developer will have to fork the housing component for the sole reason of decoupling the housing from its original parent component hierarchy.

I can see a number of ways we could ensure that none of the vacuum pump design leaks into the other projects, but all but one of them look to complicated to me (for example we could create a "parent component" API in the component data structures, but then what happens when the component documents are generated in isolation?).

I plan to address the required isolation by adopting the simplest solution I have developed: One way visibility across the component hierarchy. Parent components can see down into their children, but child components cannot see above themselves (so they cannot access their parents and therefore they also cannot access their siblings).

With that in mind, let me now circle back to the question of local component naming... I would propose the following.

1. Local component names should not reference upstream or sibling component definitions. For example, the housing component above should not be named something like jmwright1000 Vacuum Pump Housing (insert actual top level component name for jmwright1000).
2. Local components should not use ultra-generic names like "housing". After all, within the same project their may be many housings. At some point it will become confusing to the developer if every housing is just "housing".
3. Local components should be named with self-contained and complete descriptive names, such that if they are refactored and they can be discovered by their name in registries like npm. In the case of the pump housing, I don't actually have enough design details to give an example. But for Ground Sphere, the antenna should not be named GS Antenna under the first statement and should not be named antenna under the second. Instead, it should be something like 2m Quarter Wave Monopole Antenna.

I think the question of traceability is important. The reason I would want traceability is so I can see all the way back through the component's design history (including when it was a local component of the jmwright1000 project. As long as the refactored component's repo has the full commit history from before it was a top level component in its own right, then I don't think it matters where it came from. And I have done the git magic that let me pull out the commits related to a sub-directory and preserve them in a new repo (that is how the DOF repo was spawned from the commits under Sliderule). I don't do that kind of repo-fu often enough to know if that is a something we can rely on across repo tools or not. If so, then I will also have to update the description of refactoring to call for that to be part of pulling the component into its own repo. If not, then we need to create an association between the refactored component and its point of origin as a local component.

[m30-jrs]

Note to all - once we reach consensus, I need this issue left open until I capture the updated architecture concepts in the new architecture materials.

[jmwright]

The three guidelines sound good to me.

As long as the refactored component's repo has the full commit history from before it was a top level component in its own right, then I don't think it matters where it came from.

We'll need to capture your experience so that the current sliderule-rs implementation can be fixed. Currently, it just does a naive refactor where it pushes the directory to an empty git repo, adds it back via npm, then deletes the local copy. None of the git history related to the directory itself is saved.