reorganize the device packages by manufacturers

[mattetti]

As we are adding more devices, it's getting hard to find them. For instance I organized the seedstudio devices under grove which was probably a mistake.

My suggestion is to use the manufacturer name such as seeedstudio, adafruit, pimorini etc..

Thoughts?

[mattetti]

@rakyll @zankich what do you think?

[rakyll]

Do you have any idea what to do with cases like dotstar's? Even though they are named by adafruit as dotstar, APA-102 is a common protocol and there are many manufacturers that sells a similar strip and you can use the dotstar package to run them.

[mattetti]

That's really the core issue. GoBot chose to name the packages based on the chipset and it's a total PITA IMHO. You should be able to google "device you bought" + go and find the package. Most users don't know nor care what the microcontroller or chipset is called.

So I see a few options:

• create a package per low level protocol and implement "meta packages" on top (or document what devices implement the protocol).
• use popular package names: (folder adafruit, package dotstar) and document the compatibility/create alias packages.

I don't think there is a perfect solution, but I think we should first consider the user experience, especially the first time user experience. Let say I went to adafruit or seeedstudio and bought a bunch of devices, how do I find and start writing Go code for those. GoBot chose a certain pattern and I can NEVER remember the package to use for the LCD screen even though I wrote it: https://github.com/hybridgroup/gobot/blob/dev/platforms/i2c/jhd1313m1_driver.go

But at the same time, if I buy another APA-102 led strip that comes straight from China, I should be able to figure out how to use the package.

[rakyll]

The second option seems to be the best. Anyone who understands/knows about the low-level protocol can already find the popular variant and use that package.

We can also make the READMEs more Google-able by mentioning the underlying protocol.

[mattetti]

I think I agree about #2, we still need to agree on a structure or organize these packages and probably extend the template to make it easier for user to google underlying protocols etc..

@zankich @deadprogram what do you think?

[deadprogram]

Many of the devices sold by Adafruit, Seeedstudio, DFRobot, etc are the same chipsets in different packages/breakout boards. Hence separating them by manufacturer would not be best using these designations, you would need to use the OEM's designation.

In Gobot, we chose to organize by first protocol of device (GPIO, I2C), and then the actual OEM designation for the hardware chipset, to be able to accommodate the many different version sold by vendors. Example: the "BMP180" breakout boards sold by Adafruit and those sold by various other vendors all use the same Bosch BMP180.

[zankich]

Anything that is branded by a specific company should be placed in a sub folder under that manufactures name.

In situations where it's a "generic" board, which different manufactures mount the same exact sensor and have no specific branding around it, those could possibly go in a generic package and create meta packages under specific manufactures as we need?

Creating meta packages which exist under different manufactures sounds like it could work, but where does the real implementation live? Does that exist in the manufacturers package that we chose to implement first? I don't really like the idea of having each of these packages reach out into separate packages and then return types from a separate package. For instance a seedstudio.NewAccel would actually return an adafruit.Accel or whatever.

At least if there is some central package they all pull from, we won't have implementations scattered throughout the sub packages.

[rakyll]

I don't really like the idea of having each of these packages reach out into separate packages and then return types from a separate package. For instance a seedstudio.NewAccel would actually return an adafruit.Accel or whatever.

We are actually never going to make brand names the proper packager names. They will be just there for the purpose of hierarchy and organization of the actual packages.

As far as I understand, dotstar will keep being its own package, just underneath a brand.

At least if there is some central package they all pull from, we won't have implementations scattered throughout the sub packages.

If there is a generic implementation required, we can put the implementation in an internal package and provide packages on top of the internal packages.

Hence separating them by manufacturer would not be best using these designations, you would need to use the OEM's designation.

This makes me why we are not going with a flat hierarchy. We don't have to organize by OEM. Let's only have one-level with user facing names. If two devices need to share the same implementation, we can make the implementation an internal package.

[mattetti]

As far as I understand, dotstar will keep being its own package, just underneath a brand.

Agreed

If there is a generic implementation required, we can put the implementation in an internal package and provide packages on top of the internal packages.

I like this approach, we can also deal with it when it will present itself

why are we not going with a flat hierarchy?

This is a very good point :p It's my fault I wanted to nicely organize the packages so they are easier to find, I was also influenced by GoBot that organizes the adapters by device protocol. I think I really like having a flat hierarchy, it will allow for a better godoc experience.

So my vote is for:

• flat hierarchy (don't group packages by brands, refer brands in the README.md files)
• name packages after their marketing name (i.e: dotstar, piglow)
• use internal packages when we need to share implementations for different devices sharing the same interface.
• deal with conflicting package names when they will happen not before (i.e: accel3xdigital could potentially collide in the future)

[rakyll]

I am in favor of what @mattetti has voted for. Dealing with conflicting names is rather hard though without injecting protocol or brand names into the package name. Do we have a better strategy?

[zankich]

Yeah for instance the accel3xdigital package if very much associated with grove branded naming

[mattetti]

Just a reminder from Effective Go:

It's helpful if everyone using the package can use the same name to refer to its contents, which implies that the package name should be good: short, concise, evocative. By convention, packages are given lower case, single-word names; there should be no need for underscores or mixedCaps. Err on the side of brevity, since everyone using your package will be typing that name. And don't worry about collisions a priori. The package name is only the default name for imports; it need not be unique across all source code, and in the rare case of a collision the importing package can choose a different name to use locally. In any case, confusion is rare because the file name in the import determines just which package is being used.

Two seems things to be pertinent:

• keep names concise
• don't worry about collisions a priori

Adding the name of the OEM or some sort of abbreviation seems wrong to me. That's also why I had opted for some sort of folders structure initially. In practice, I'm not sure how often this issue will come up but I think it's worth dealing with it when it will come (feel free to blame them then ;))

[zankich]

So then branded things like grove could have its own sub folder and everything else can be flat?

[mattetti]

No sub folders, everything flat and if we find conflicts we can deal with them then