chore: project maintenance - docs and tasks

.github/workflows/main.yml

@@ -2,14 +2,14 @@ name: tests
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
     paths-ignore:
       - docs/*
       - '**/*.md'
       - test/*.go
 
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
 
 jobs:
 

.gitignore

@@ -8,6 +8,7 @@ test/c8y_test/application.properties
 test/c8y_test/debug.test
 test/c8y_test/application.setup.properties
 c8y.env
+*.env
 main.exe
 *.log
 output

README.md

@@ -1,6 +1,6 @@
 # go-c8y
 
-Unofficial Go client for [Cumulocity](http://cumulocity.com/guides/reference/rest-implementation/).
+Unofficial Go client for [Cumulocity IoT](https://cumulocity.com/api/core/).
 
 ![tests](https://github.com/reubenmiller/go-c8y/workflows/tests/badge.svg)
 [![Go Report Card](https://goreportcard.com/badge/github.com/reubenmiller/go-c8y)](https://goreportcard.com/report/github.com/reubenmiller/go-c8y)
@@ -11,50 +11,18 @@ Unofficial Go client for [Cumulocity](http://cumulocity.com/guides/reference/res
 
 We encourage you to try the package in your projects, just keep these caveats in mind, please:
 
-* **This is a work in progress.** Not all of the Cumulocity REST API is covered, and the HTTP client is very simple. In the future the HTTP Client will be improved to support retries on failures, client side rate limiting, prometheus api metrics, mqtt client.
+* **This is a work in progress.** Not all of the Cumulocity IoT REST API is covered, and the HTTP client is very simple. In the future the HTTP Client will be improved to support retries on failures, client side rate limiting, prometheus api metrics, mqtt client.
 
-* **There are no guarantees on API stability.** The general mechanics of the golang API are still being worked out. The balance between helpers and clarity is still being found. Given limited access to all available Cumulocity Servers versions, compatibility to all Cumulocity versions is not guarenteed, however since Cumulocity takes an additive approach to new features, it is more likely that the new features will be missing rather than existing API breaking (excluding deprecated features)
+* **There are no guarantees on API stability.** The general mechanics of the golang API are still being worked out. The balance between helpers and clarity is still being found. Given limited access to all available Cumulocity IoT versions, compatibility to all Cumulocity IoT versions is not guaranteed, however since Cumulocity IoT takes an additive approach to new features, it is more likely that the new features will be missing rather than existing API breaking (excluding deprecated features)
 
+## Usage
 
-
-## Installation
-
-Install the package with `go get`:
-
-    go get -u github.com/reubenmiller/go-c8y/c8y_test
-
-Or, add the package to your `go.mod` file:
-
-    require github.com/reubenmiller/go-c8y/c8y_test master
-
-Or, clone the repository:
-
-    git clone https://github.com/reubenmiller/go-c8y/c8y_test.git && cd go-c8y
-
-
-## Running the tests
-
-1. Create an `application.properties` file in the `./c8y_test` folder and set the Cumulocity host, tenant and user credentials. The user must have admin rights in the specified tenant.
-
-    ```sh
-    c8y.host=
-    c8y.tenant=
-    c8y.username=
-    c8y.password=
-    testing.cleanup.removeDevice=false
-    ```
-
-2. Execute the integration tests
+1. Add the package to your project using `go get`:
 
     ```sh
-    go test -timeout 30s github.com/reubenmiller/go-c8y/c8y_test
-
-    # race detector. Onlwindows use backslashes
-    go test -race -timeout 30s github.com/reubenmiller/go-c8y/test/c8y_test -run "^(TestRealtimeSubscriptions_Unsubscribe)$
+    go get -u github.com/reubenmiller/go-c8y/c8y
     ```
 
-## Usage
-
 1. Create a `main.go` file with the following
 
     ```golang
@@ -89,26 +57,53 @@ Or, clone the repository:
     }
     ```
 
-2. Execute the application
+2. Set the credentials via environment variables
+
+    **Windows (PowerShell)**
 
-    On Windows
     ```sh
-    set C8Y_HOST=https://cumulocity.com
-    set C8Y_TENANT=mycompany
-    set C8Y_USER=username
-    set C8Y_PASSWORD=password
-    go run main.go
+    $env:C8Y_HOST = "https://cumulocity.com"
+    $env:C8Y_TENANT = "mycompany"
+    $env:C8Y_USER = "username"
+    $env:C8Y_PASSWORD = "password"
     ```
 
-    On Linux/MacOS
+    **Linux/MacOS**
+
     ```sh
     export C8Y_HOST=https://cumulocity.com
     export C8Y_TENANT=mycompany
     export C8Y_USER=username
     export C8Y_PASSWORD=password
+    ```
+
+3. Run the application
+
+    ```sh
     go run main.go
     ```
 
 ## Examples
 
 More examples can be found under the `examples` folder.
+
+## Development
+
+### Running the tests
+
+To run the tests you will need to install [go-task](https://taskfile.dev/installation/), or use the dev container which includes go-task.
+
+1. Create a dotenv file `.env` to the root folder and add your Cumulocity credentials to use for the tests
+
+    ```sh
+    C8Y_HOST=https://cumulocity.com
+    C8Y_TENANT=mycompany
+    C8Y_USER=username
+    C8Y_PASSWORD=password
+    ```
+
+2. Execute the tests
+
+    ```sh
+    task test
+    ```

Taskfile.yml

@@ -3,14 +3,15 @@ version: '3'
 env:
   ENV: testing
 
-dotenv: ['c8y.env', '{{.ENV}}/c8y.env', '{{.HOME}}/c8y.env']
+dotenv: ['.env', 'c8y.env', '{{.ENV}}/c8y.env', '{{.HOME}}/c8y.env']
 
 tasks:
   test:
     desc: Test all packages
     cmds:
       - task: test-c8y
       - task: test-microservice
+      - task: test-race
 
   test-c8y:
     desc: Test c8y package
@@ -22,6 +23,11 @@ tasks:
     cmds:
       - go test -v -timeout 30m github.com/reubenmiller/go-c8y/test/microservice_test
 
+  test-race:
+    desc: Test for race conditions
+    cmds:
+      - go test -race -timeout 30s github.com/reubenmiller/go-c8y/test/c8y_test -run "^(TestRealtimeSubscriptions_Unsubscribe)$"
+
   lint:
     desc: Linting
     cmds: