Protolock Version: 20210218T172155Z
The proto-backwards-compatibility
plugin is a Maven plugin to
run a backwards compatibility check on a set of protobuf IDL files. The plugin
can be integrated into various phases of a maven build to check that any changes to
a set of .proto files are backwards compatible. This ensures that these changes do
not impact existing users that haven't had a chance to update to these latest changes.
A proto.lock file is created in the proto source directory to keep
track of the state of the .proto files. This file is updated when a non-breaking change
is made, and should be checked in along with any other changes.
It is also possible to force any breaking changes and reset the current state by either
- deleting the proto.lock file. It will then reinitialize the next time the plugin is run.
- or by specifying parameter property
acceptBreakingChanges
(-DacceptBreakingChanges=true
)
In order to maintain backwards compatibility for your set of .proto files, a few rules must be followed when making updates. Please refer here to avoid breaking changes: https://developers.google.com/protocol-buffers/docs/proto#backwards-compatibility
The os-maven-plugin
extension (https://github.com/trustin/os-maven-plugin)
must be added to your project's pom.xml file in order for this plugin to work.
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>1.4.1.Final</version>
</extension>
</extensions>
<plugins>
<plugin>
<groupId>com.salesforce.servicelibs</groupId>
<artifactId>proto-backwards-compatibility</artifactId>
<version>${proto-backwards-compatibility.version}</version>
<configuration>
<!-- Optional alternative protos location -->
<protoSourceRoot>src/main/proto</protoSourceRoot>
<!-- Optional alternative proto.lock location -->
<lockDir>src/main/proto</lockDir>
</configuration>
<executions>
<execution>
<goals>
<goal>backwards-compatibility-check</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<protoSourceRoot>
(${basedir}/src/main/proto
) - The directory where proto sources can be found.<lockDir>
(defaults to root of proto files) - The directory where proto.lock will be kept.<options>
(empty) - Additional command line options to pass to protolock.
<configuration>
<plugins>
<protoSourceRoot>src/main/proto</protoSourceRoot>
<options>--ignore=target/</options>
<lockDir>${project.basedir}</lockDir>
</plugins>
</configuration>
Protolock has plugin support, to allow for new rules to be enforced. Protolock plugins are referenced by adding the following additional configuration to your pom.xml.
<configuration>
<plugins>
<!-- Plugin executable distributed by Maven -->
<plugin>com.salesforce.servicelibs:sample-plugin:0.1.0-SNAPSHOT:${os.detected.classifier}</plugin>
<!-- Plugin executable found on the system path -->
<plugin>sample-plugin</plugin>
</plugins>
</configuration>
Thank you to Steve Manuel for his protocol buffer compatiblity tracker which is a key component of this plugin: https://github.com/nilslice/protolock