10

I wonder what is the best practice for protocol buffer regarding source repository (e.g. git) :

Do I have to put ONLY the .proto file in the repository and let anyone else who uses the source code to regenerate classes code with protoc compiler ? or is it a best pratice to put both .proto files AND source code generated by protoc compiler ?

kondor
  • 783
  • 1
  • 8
  • 22

2 Answers2

12

You should never check in generated code if you can avoid it.

If you check in generated code, you take on multiple risks, such as:

  • You risk losing the knowledge of how to correctly regenerate that code. If it's not automated as part of the build, it's too easy to forget to document, or to have the documentation be wrong.
  • You risk the generated code getting out-of-sync with the schema. For example, someone could make a change to the .proto file but forget to update the generated code. Their changes won't actually "take effect" until someone else later on regenerates the generated code for some other reason -- and then all of the sudden they see side effects they weren't expecting.
  • Your generated code might be for a different version of protocol buffers than what the builder has installed. In this case it won't work correctly, since it's necessary to use the exact same version of the compiler and runtime library.

If for some reason you absolutely have to check in generated code, I highly recommend creating an automated test that checks if the checked-in code matches what protoc would generate if run fresh. (For example, the protobuf repository itself contains checked-in copies of generated code for descriptor.proto because this code is needed to compile protoc, creating a circular dependency. But there is a unit test that checks that the checked-in code matches what protoc would generate.)

Kenton Varda
  • 41,353
  • 8
  • 121
  • 105
  • However, if I don't check in, a client cannot use the library. For example, say I create a golang library and I want anyone to be able to use my library. In that case, it's justified that I check in the generated code? – Mo... Aug 13 '20 at 22:05
  • @MoK I would argue that anyone building your library _from source code_ should be expected to install the necessary tools to build it. However, when publishing a packaged version of your library for others to depend on, the package should include any files needed so that the dependent doesn't need to install special tools. – Kenton Varda Aug 14 '20 at 23:32
  • 1
    Thank you. That would mean generated codes should be checked in for golang as there is no separation between two. It just git check out and gets compiled together behind the scene. So, if the generated codes are not included, it would result in an error. – Mo... Aug 17 '20 at 04:25
  • 2
    @MoK To be honest, I don't know what the best practices are for Go specifically, as I've never written any Go. I'm sure the Go team has thought about this and you should look up their advice. – Kenton Varda Aug 18 '20 at 14:19
1

If your project is commonly used in its source code form (e.g. a library or a program every user is supposed to compile himself), I would make available release packages that have the generated files.

But I wouldn't put the generated files into the repository directly. And if most users will use a compiled binary, it is not that important to provide easy-to-compile source packages either. The protobuf generator then becomes just another build dependency.

jpa
  • 10,351
  • 1
  • 28
  • 45