Project and Docker naming and versions

This document shares the best practices of naming and versioning a module and its Docker image.

Introduction
There is no strict convention regarding naming modules and their images, but described bellow are some rules of a good practice that we strongly recommend to everyone. Remember, the best names are always self-explanatory!
Module naming and versioning 
The unique identity of a module is comprised of the moduleName, a string, and the versionName, also a string. The combination of moduleName and versionName uniquely identifies the module across all locations. This consistency prevents ambiguity to users and those who might need to debug an edge application. 
Platform
The module is registered in the platform according to the database entry with the following fields;
moduleName: 'mqtt-ingress'
versionName: '1.0.0'
GitHub
In the version control platform such as GitHub, the moduleName is the name of the repository. The versionName is the tag. 
We recommend that releases should always be tagged from main branch.
DockerHub
In DockerHub, the moduleName is the name of the repository. The versionName is the image tag. 
It is best practice to remove the latest tag from DockerHub. 
Versioning process
To comply with the above consistent approach to naming and versioning, the following recipe describes how to release a new version of a module. 
Given a GitHub repo with the module code:
1.Optionally create a branch from main and name it as required
2.(Update code as required)
3.Update the Module.yaml and change the versionName to i.e. v2.0.1
4.When complete, merge this branch into main
5.In GitHub - go to tags, and create a new release, with the tag v2.0.1
6.Build and publish the image to Dockerhub with the same tag v2.0.1
7.Register the module with weeve, using the Module.yaml
There is a lot of articles online on versioning your software, i.e. Semantic Versioning 2.0.0​
Naming Modules
The best approach would be to choose a module name that best describes its purpose. Similarly to choosing the names for your methods and variables when you code, a module name should be short and clear. Remember that very often the module will be used by your colleagues, who will be building weeve data services, or external users if you decide to make your module public on our platform. They should be able to get a good sense of what your module does just by looking at its name in Designer section of weeve IoT Platform and without a further need to explore the module documentation.
Let's look at some examples of our modules and their names:
​MQTT Ingress - is an input module that ingresses data from MQTT broker to a data service,
​Camera Capture - is a module that inputs a frame/image captured by a camera attached to a device,
​Comparison Filter - is a processing module that filters data according to some query,
​HTTP Egress - is a module outputting data from a data service to some endpoint over an HTTP protocol,
​Slack Alert - is a module sending alerts to chosen Slack channels
Naming Modules' Docker Images
We strongly recommend making your module's Docker image name composed of your (or your organization's) name and the module name <organization_name>/<module_name>. This way your modules could be easily recognized on devices that use them.
Let's look at the same modules as above and their Docker images names:
MQTT Ingress:
moduleName: mqtt-ingress
Docker image name: weevenetwork/mqtt-ingress
Camera Capture:
moduleName: camera-capture
Docker image name: weevenetwork/camera-capture
Comparison Filter:
moduleName: comparison-filter
Docker image name: weevenetwork/comparison-filter
HTTP Egress:
moduleName: http-egress
Docker image name: weevenetwork/http-egress
Slack Alert:
moduleName: slack-alert
Docker image name: weevenetwork/slack-alert

Creating Module YAML

Writing README for modules

Last modified 7mo ago