Rubberduck Nuggets (discussion)

[retailcoder]

The idea of having some kind of "code snippets" feature built into Rubberduck has been floating around forever, without being given much attention. In a recent chat discussion however, an idea surfaced, about implementing some kind of "NuGet for VBA" repository of "functionality packages" that our users could download and integrate into their projects. I'm thinking of hosting the "nuggets" on a dedicated repository, under the wing of the rubberuduck-vba GitHub organisation: https://github.com/rubberduck-vba/nuggets

The problem being solved is as follows:

• Provide Rubberduck users with a way to easily add code modules to their projects from a trusted source, implementing various host-independent, common functionalities with object-oriented, tested code that is readily consummable by our users' projects.

IMO a first iteration doesn't need to address every single tricky details and everything that could possibly go wrong with simply pulling files from a GitHub repository and adding them to a VBA/VB6 project.

But we do need to take a number of things into consideration.

• How is a nugget licensed? I'm thinking either MIT, or CC0/WTFPL. Last thing we want is a license that makes our users wonder whether using nuggets is binding in any way - IMO it shouldn't be. It's just code we think is useful and well-written, that our users could download and use and modify in whichever way they feel like in their own projects.

• How to we organize things? The nuggets should be browsable in some kind of UI, and include metadata, such as:

  • Nugget name
  • Short description of the packaged functionality / purpose of the code
  • Date of publication & version number
  • Number of files in the package
  • Size of the download
  • (number of downloads? could we even track that if they're just files in a GH repo?)

  Seems a small XML file would do the job - something like this?

<?xml version="1.0" encoding="utf-8" xmlns:rubberduck="https://github.com/rubberduck-vba/nuggets"?>
<rubberduck:nugget name="ProgressIndicator" host="VBA" version="1.0" published="2018-05-18" tree="36a653a8f7ceb0f693586645c06766b2eb943ad6" description="A configurable progress indicator class that makes it easy to report progress of long-running operations.">
    <File type="class" name="ProgressIndicator.cls" />
    <File type="userform" name="ProgressView.frm" />
</rubberduck:nugget>

• Do we track a project's nuggets? For VB6 that's rather easy: we can add custom properties to the .vbp file. But for VBA? Per-project metadata was one of the pain points of the defunct source control feature, do we want to go there again? If not, how else? Would not tracking nuggets in a project really be a problem? For a first iteration? And if we do track "installed" nuggets, then do we allow "restore" from the repository (i.e. re-download and overwrite)? What if the files were renamed, or modified? IMO for a first iteration it might be best to leave all that on the user, and only warn about naming conflicts when they arise - i.e. if a user downloads the ProgressIndicator nugget and renames all the classes and then downloads it again, we just add them again. If the modules weren't renamed, we prompt to overwrite, and that's the end of it.

• Contributing? Users will eventually want to contribute their own nuggets. We need to have clear contribution guidelines. I'd want nuggets to be vetted by @rubberduck-vba/dev, but essentially public domain, and thoroughly reviewed and ideally including RD unit tests and/or a working, executable module that illustrates how it's used.

---

Other ideas? Concerns? Discussion is open!

[bclothier]

Let's simplify the tracking part: Assume that a "nugget" is strictly for consumption only and track the hash of the entire content of the nuggets to a specific version. If hash doesn't match, assume it is no good and replace it. After all, one shouldn't be editing a nugget just to suit a particular taste --- defeats the whole point of nuggets and they can always opt to actually import it as their own, rather than using it as a nugget (with all the update & dependency management implied).

That is going to be important because if we allow dependency resolution, we must know that it's a particular version that is known to work with the dependent's version, so hashing the module contents is a simple way to evaluate whether it's of a particular version.

[bclothier]

WRT the package design and management, I'd rather use some existing framework than invent our own. The dependency resolution alone can get hairy fast and I'd rather not have to reinvent wheel there. It'd be nice to be able to use nuget but review of its documentation suggests that it's way too deeply-baked in the .NET ecosystem that using it to deliver VBA code just doesn't make sense, unfortunately. A better candidate would be ZeroInstall which provides DLLs that we can leverage for management of finding, downloading, resolving, leaving us with only the concern of actually installing/removing the packages.

API documentation C-sharp sample Product comparison

[retailcoder]

@bclothier so if I download the ProgressIndicator nugget and change the font on the form, or change the default title string constant, I've just defeated the purpose of using a nugget? I wasn't thinking of implementing update & dependency management just yet, precisely because that's an easily hairy thing.

To be clear, "nuggets" would simply be centralized code that you can add to your project from some RD UI, as opposed to maintaining a "toolbox" on your local drive with a bunch of classes you always end up adding to every VBA project you work on. Talking DLLs and binaries has deployment and registration implications that are just as hairy and much more complicated to use for our users IMO.

[mansellan]

I agree that the ability to browse and easily download / install trusted collections of modules has great value of itself. But I'd like to think there was a pathway from there to being later able to implement managed dependencies, as that allows the community to build ever upwards (think of how many NuGets take Json.Net as a dependency, for example).

IMO, one of the issues with SC was the use of external files to track project state - this had implications for portability and shared development. We don't have the option in VBA add custom project data, but I don't see much downside to taking any given content and writing it as comments to a module. This could be XML for example, and validated against a schema. It could open up new possibilities, for example an Add Folder command in CE, which could lead to a full drag & drop UX.

[Imh0t3b]

Great idea!

No more bad code from unkown sources. But shouldn't be collecting and reviewing code the first step? Easy install and update of code is far less important for me. There should be lots of reviewed code on codereview.stackexchange.com that we can start with. So the only thing to solve is the licence problem, then we can start collecting? The rest can be discussed later, let's go!

[Vogel612]

"Quickfire Questions" in no particular order, as they come to my mind when thinking about what could go wrong with this. (N.B. that's just the stuff that came to my mind at 1 AM, given some time I can probably think of more messy things):

---

Are License definitions optional or required? Are License definitions standardized or free-form? (cf. SPDX license identifiers) How are artifacts identified exactly. Do they get a name? Or a group & name? Are versions required to have a specific format? Are version requirements specifiable as ranges? How do we keep track of which dependencies the project has? There's no infrastructure around that whatsoever. Do we check for updates? If yes, how often? When does resolving and downloading dependencies happen? How do we handle transitive dependencies, if we even allow them?

[rkapka]

I have been learning the Go programming language lately and its creators came up with something they call semantic import versioning (you can read about it here). If Rubberduck Nuggets ever get implemented, I think this versioning scheme might be worth considering.