development.md

go-observing development

The following instructions are useful during development.

Note: This has been tested on Linux and Darwin/macOS. It has not been tested on Windows.

Prerequisites for development

🤔 The following tasks need to be complete before proceeding. These are "one-time tasks" which may already have been completed.

1. The following software programs need to be installed:
   1. git
   2. make
   3. docker
   4. go

Install Git repository

1. Identify git repository.

   export GIT_ACCOUNT=senzing-garage
   export GIT_REPOSITORY=go-observing
   export GIT_ACCOUNT_DIR=~/${GIT_ACCOUNT}.git
   export GIT_REPOSITORY_DIR="${GIT_ACCOUNT_DIR}/${GIT_REPOSITORY}"
   

2. Using the environment variables values just set, follow steps in clone-repository to install the Git repository.

Dependencies

1. A one-time command to install dependencies needed for make targets. Example:

   cd ${GIT_REPOSITORY_DIR}
   make dependencies-for-development
   

2. Install dependencies needed for Go code. Example:

   cd ${GIT_REPOSITORY_DIR}
   make dependencies
   

Lint

1. Run linting. Example:

   cd ${GIT_REPOSITORY_DIR}
   make lint
   

Developing gRPC client and server SDK

The following instructions were used to create a go module and other example generated source code.

1. Follow the Go Quick start tutorial to prepare an environment.

2. Generating client and server code. Example:

   cd ${GIT_REPOSITORY_DIR}
   make generate
   

   1. In ${GIT_REPOSITORY_DIR}/observerpb, files with _grpc. in the filename contain the following:
      • Interface types (or stubs) for clients to call with the methods defined in the services.
      • Interface types for servers to implement, also with the methods defined in the services.
      • In other words, its the "gRPC" code that handles the network traffic, not the message content.
   2. In ${GIT_REPOSITORY_DIR}/observerpb, files without _grpc. in the filename contain the following:
      • protocol buffer code to populate, serialize, and retrieve request and response message types.
      • In other words, it manages message content, not the network traffic.

3. References:

   1. gRPC Documents for Go
      1. Go Quick start
   2. Thread safety

Test

1. Run tests. Example:

   cd ${GIT_REPOSITORY_DIR}
   make clean setup test
   

Coverage

Create a code coverage map.

1. Run Go tests. Example:

   cd ${GIT_REPOSITORY_DIR}
   make clean setup coverage
   

   A web-browser will show the results of the coverage. The goal is to have over 80% coverage. Anything less needs to be reflected in testcoverage.yaml.

Documentation

1. View documentation. Example:

   cd ${GIT_REPOSITORY_DIR}
   make clean documentation
   

2. If a web page doesn't appear, visit localhost:6060.

3. Senzing documentation will be in the "Third party" section. github.com > senzing-garage > go-observing

4. When a versioned release is published with a v0.0.0 format tag, the reference can be found by clicking on the following badge at the top of the README.md page. Example:

   

5. To stop the godoc server, run

   cd ${GIT_REPOSITORY_DIR}
   make clean
   

References