Merge pull request #2 from Azure-Samples/ethanperry/organization-and-…

…initial-docs

Ethanperry/organization and initial docs

.github/workflows/docker_build.yml

@@ -0,0 +1,18 @@
+name: docker_build
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - release/*
+
+jobs:
+  docker_build:
+    name: 'Build docker containers'
+    runs-on: ubuntu-latest
+    environment: production
+
+    defaults:
+      run:
+        shell: bash
+

.gitignore

@@ -396,3 +396,7 @@ FodyWeavers.xsd
 
 # JetBrains Rider
 *.sln.iml
+
+bin
+cover.tmp.out
+coverage.out

README.md

@@ -1,14 +1,18 @@
-# Project Name
+# Azure IoT Operations Dev Toolbox
 
-(short, 1-3 sentenced, description of the project)
+The AIO dev toolbox is the source of tools, samples, and other resources for customers of AIO.
+
+## Contributing
+
+Please view the developer guides in the docs directory to get started with contributions. Get started with the [Organization docs](./docs/ORGANIZATION.md).
 
 ## Features
 
-This project framework provides the following features:
+This project provides the following tools:
 
-* Feature 1
-* Feature 2
-* ...
+* Krill MQTT Data Simulator
+* HTTP Callout Server
+* GRPC Callout Server
 
 ## Getting Started
 

docker/example/Dockerfile

@@ -0,0 +1,9 @@
+# syntax=docker/dockerfile:1
+
+FROM mcr.microsoft.com/oss/go/microsoft/golang:1.21-cbl-mariner2.0
+
+COPY go.mod /tool/go.mod
+COPY go.sum /tool/go.sum
+COPY lib /tool/lib
+COPY tools/example /tool/example
+

docs/ORGANIZATION.md

@@ -0,0 +1,55 @@
+# Toolbox Organization
+
+## Structure
+
+The AIO toolbox is a collection of several tools for customers of AIO. To keep the project understandable and extensible to future additions, the following conventions should be followed for repository structure.
+
+```
+├── lib
+│   ├── library1
+│   ├── ...
+│   ├── libraryN
+├── samples
+│   ├── tool1
+│   │   ├── config.yml
+│   │   ├── config.json
+│   ├── ...
+│   ├── toolN
+├── tools
+│   ├── tool1
+│   │   ├── cmd
+│   │   │   ├── main.go
+│   │   ├── pkg
+│   │   │   ├── pkg1
+│   ├── ...
+│   ├── toolN
+├── docker
+│   ├── tool1
+│   │   ├── Dockerfile
+│   ├── ...
+│   ├── toolN
+├── go.mod
+├── go.sum
+├── magefile.go
+└── README.md
+```
+
+__Libraries__ which are shared between multiple tools should be stored in the lib directory. This library can be incorporated into projects beyond AIO tools and such documentation will be available on the _go.dev_ documentation site.
+
+__Samples__ are configuration files which have been created for specific sample usages of a tool. Multiple configuration files can live in each sample folder for different samples which utilize the same tool.
+
+__Tools__ are AIO specific tools which may have their own internal packages stored within the pkg folder. Other top-level folders in each tool are allowed, though it is recommended to minimize the number of top-level folders. Each tool must also have its own cmd directory where the entrypoint is located.
+
+__Dockerfiles__ for relavent docker images are stored for each tool under the docker directory. They are siloed into their own directories for each tool.
+
+__Mage Commands__ are located within the magefile.go. Mage commands should be written in such a way that they apply to any given tool based on a parameter. Mage commands should not be targeted at a specific tool itself. If such a command is required, a magefile within the tool directory should be produced.
+
+## Linting & Formatting Requirements
+
+Linting and formatting rules are applied to all tools and libraries based on a linting configuration set up and applied via mage commands.
+
+## Example Tool
+
+Please view the example tool in `tools/example` for an example of how to contribute a new tool to the AIO toolbox.
+
+_Note_: tools can be written in any language including minimal tools such as bash scripts. The tools are written in golang in this document for example purposes.

go.mod

@@ -0,0 +1,18 @@
+module github.com/Azure-Samples/aio-dev-toolbox/toolbox
+
+go 1.21.3
+
+require (
+	github.com/magefile/mage v1.15.0
+	github.com/princjef/mageutil v1.0.0
+)
+
+require (
+	github.com/VividCortex/ewma v1.1.1 // indirect
+	github.com/cheggaaa/pb/v3 v3.0.4 // indirect
+	github.com/fatih/color v1.9.0 // indirect
+	github.com/mattn/go-colorable v0.1.4 // indirect
+	github.com/mattn/go-isatty v0.0.12 // indirect
+	github.com/mattn/go-runewidth v0.0.7 // indirect
+	golang.org/x/sys v0.0.0-20200116001909-b77594299b42 // indirect
+)

go.sum

@@ -0,0 +1,36 @@
+github.com/VividCortex/ewma v1.1.1 h1:MnEK4VOv6n0RSY4vtRe3h11qjxL3+t0B8yOL8iMXdcM=
+github.com/VividCortex/ewma v1.1.1/go.mod h1:2Tkkvm3sRDVXaiyucHiACn4cqf7DpdyLvmxzcbUokwA=
+github.com/cheggaaa/pb v2.0.7+incompatible/go.mod h1:pQciLPpbU0oxA0h+VJYYLxO+XeDQb5pZijXscXHm81s=
+github.com/cheggaaa/pb/v3 v3.0.4 h1:QZEPYOj2ix6d5oEg63fbHmpolrnNiwjUsk+h74Yt4bM=
+github.com/cheggaaa/pb/v3 v3.0.4/go.mod h1:7rgWxLrAUcFMkvJuv09+DYi7mMUYi8nO9iOWcvGJPfw=
+github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4=
+github.com/fatih/color v1.9.0 h1:8xPHl4/q1VyqGIPif1F+1V3Y3lSmrq01EabUW3CoW5s=
+github.com/fatih/color v1.9.0/go.mod h1:eQcE1qtQxscV5RaZvpXrrb8Drkc3/DdQ+uUYCNjL+zU=
+github.com/magefile/mage v1.15.0 h1:BvGheCMAsG3bWUDbZ8AyXXpCNwU9u5CB6sM+HNb9HYg=
+github.com/magefile/mage v1.15.0/go.mod h1:z5UZb/iS3GoOSn0JgWuiw7dxlurVYTu+/jHXqQg881A=
+github.com/matryer/is v1.3.0 h1:9qiso3jaJrOe6qBRJRBt2Ldht05qDiFP9le0JOIhRSI=
+github.com/matryer/is v1.3.0/go.mod h1:2fLPjFQM9rhQ15aVEtbuwhJinnOqrmgXPNdZsdwlWXA=
+github.com/mattn/go-colorable v0.1.2/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
+github.com/mattn/go-colorable v0.1.4 h1:snbPLB8fVfU9iwbbo30TPtbLRzwWu6aJS6Xh4eaaviA=
+github.com/mattn/go-colorable v0.1.4/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
+github.com/mattn/go-isatty v0.0.8/go.mod h1:Iq45c/XA43vh69/j3iqttzPXn0bhXyGjM0Hdxcsrc5s=
+github.com/mattn/go-isatty v0.0.10/go.mod h1:qgIWMr58cqv1PHHyhnkY9lrL7etaEgOFcMEpPG5Rm84=
+github.com/mattn/go-isatty v0.0.11/go.mod h1:PhnuNfih5lzO57/f3n+odYbM4JtupLOxQOAqxQCu2WE=
+github.com/mattn/go-isatty v0.0.12 h1:wuysRhFDzyxgEmMf5xjvJ2M9dZoWAXNNr5LSBS7uHXY=
+github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
+github.com/mattn/go-runewidth v0.0.7 h1:Ei8KR0497xHyKJPAv59M1dkC+rOZCMBJ+t3fZ+twI54=
+github.com/mattn/go-runewidth v0.0.7/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
+github.com/princjef/mageutil v1.0.0 h1:1OfZcJUMsooPqieOz2ooLjI+uHUo618pdaJsbCXcFjQ=
+github.com/princjef/mageutil v1.0.0/go.mod h1:mkShhaUomCYfAoVvTKRcbAs8YSVPdtezI5j6K+VXhrs=
+golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20191008105621-543471e840be/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20191128015809-6d18c012aee9/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42 h1:vEOn+mP2zCOVzKckCZy6YsCtDblrpj/w7B9nxGNELpg=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+gopkg.in/VividCortex/ewma.v1 v1.1.1/go.mod h1:TekXuFipeiHWiAlO1+wSS23vTcyFau5u3rxXUSXj710=
+gopkg.in/cheggaaa/pb.v2 v2.0.7/go.mod h1:0CiZ1p8pvtxBlQpLXkHuUTpdJ1shm3OqCF1QugkjHL4=
+gopkg.in/fatih/color.v1 v1.7.0/go.mod h1:P7yosIhqIl/sX8J8UypY5M+dDpD2KmyfP5IRs5v/fo0=
+gopkg.in/mattn/go-colorable.v0 v0.1.0/go.mod h1:BVJlBXzARQxdi3nZo6f6bnl5yR20/tOL6p+V0KejgSY=
+gopkg.in/mattn/go-isatty.v0 v0.0.4/go.mod h1:wt691ab7g0X4ilKZNmMII3egK0bTxl37fEn/Fwbd8gc=
+gopkg.in/mattn/go-runewidth.v0 v0.0.4/go.mod h1:BmXejnxvhwdaATwiJbB1vZ2dtXkQKZGu9yLFCZb4msQ=

lib/example/example.go

@@ -0,0 +1,11 @@
+package example
+
+import "fmt"
+
+// Example shows that all exported symbols must have a comment like this.
+type Example struct {}
+
+// Print shows that the exported symbol comments applies to functions as well.
+func (*Example) Print() {
+	fmt.Println("Example library")
+}

lib/example/example_test.go

@@ -0,0 +1,8 @@
+package example
+
+import "testing"
+
+// Every library must have a test file and must meet a minimum test coverage to be merged into the toolbox.
+func TestMain(m *testing.M) {
+	m.Run()
+}

mageerrors.go

@@ -0,0 +1,45 @@
+package main
+
+import "fmt"
+
+// PackageMissingTestFileError is an error describing a package which is missing a test file.
+type PackageMissingTestFileError struct {
+	name string
+}
+
+func (err *PackageMissingTestFileError) Error() string {
+	return fmt.Sprintf(
+		"package %q is missing a test file and is not listed in the packages excluded from requiring a test file",
+		err.name,
+	)
+}
+
+type Coverage struct {
+	path       string
+	name       string
+	percentage float64
+	expected   float64
+}
+
+func (coverage *Coverage) Error() string {
+	return fmt.Sprintf(
+		"block %q in file %q has an inadequate unit test coverage percentage of %0.2f%% where %0.2f%% was expected",
+		coverage.name,
+		coverage.path,
+		coverage.percentage,
+		coverage.expected,
+	)
+}
+
+type InadequateOverallCoverageError struct {
+	percentage float64
+	expected   float64
+}
+
+func (err *InadequateOverallCoverageError) Error() string {
+	return fmt.Sprintf(
+		"inadequate overall unit test coverage percentage of %0.2f%% where %0.2f%% was expected",
+		err.percentage,
+		err.expected,
+	)
+}