# CMVR-ES Proto Contract

This module builds from the protobuf snapshot committed under
`src/main/proto/cmvr`. The snapshot currently corresponds to CMVR-ES commit
`67566e8aea8b6cb8735556af02d25705f36cce74`.

Normal Maven builds do not access the CMVR-ES Git repository and never modify
`src/main`. The protobuf plugin generates Java and gRPC sources under
`target/generated-sources/protobuf`, which Maven automatically adds to the
compile source roots.

## Updating to the latest upstream proto

Run one command from the repository root.

Windows:

```powershell
.\bin\update-grpc-protos.bat
```

Linux:

```shell
bash ./bin/update-grpc-protos.sh
```

The script resolves the latest commit on the configured upstream branch,
updates the committed `.proto` snapshot and `cmvr.es.proto.revision`, and runs
a gRPC verification build. It refuses to overwrite uncommitted local proto
changes. Review and commit the proto files and `pom.xml` together.

Normal builds still never access the upstream Git repository. Only this
explicit update command pulls and updates protocol sources.

Do not run the update command on a production server. Build the application in
a development or CI environment and deploy the resulting JAR and environment
configuration. If a Linux server must build from source, a normal
`mvn clean package` uses the committed proto snapshot and does not require
access to the CMVR-ES Git repository.

## Jenkins

The normal Jenkins build/deploy job should only build the checked-out business
repository:

```shell
mvn -B clean package -DskipTests
```

Archive or deploy `cmvr-iot-admin/target/cmvr-iot-admin.jar` using the existing
deployment steps. This job does not need credentials or network access for the
CMVR-ES Git repository.

When an upstream protocol update is required, run
`bash ./bin/update-grpc-protos.sh` in a separate, manually triggered Jenkins
job (or on a developer machine) that can access the internal Git repository.
Review and commit the changed proto files and `pom.xml` to the business
repository, then let the normal build/deploy job build that commit. Do not
deploy an uncommitted protocol update directly from a temporary Jenkins
workspace.

## Inspecting a pinned snapshot

To inspect the currently pinned upstream snapshot without changing source
files, explicitly enable the fetch profile:

```shell
mvn -pl cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib \
    -Pfetch-cmvr-es-protos initialize
```

The profile checks out the exact `cmvr.es.proto.revision` into
`target/cmvr-es`; it does not copy or delete source files. Compare
`target/cmvr-es/protos/cmvr` with `src/main/proto/cmvr`, review the protocol
changes, update the committed snapshot and revision together, then run a clean
build. The repository URL, lookup branch, and revision can be overridden
explicitly with `-Dcmvr.es.repository=...`, `-Dcmvr.es.proto.branch=...`, and
`-Dcmvr.es.proto.revision=...`.