Merge pull request #24665 from smarterclayton/protodocs

docs/devel/adding-an-APIGroup.md

@@ -64,6 +64,11 @@ Step 2 and 3 are mechanical, we plan on autogenerate these using the cmd/libs/go
     1. Touch types.generated.go in pkg/apis/`<group>`{/, `<version>`};
     2. Run hack/update-codecgen.sh.
 
+3. Generate protobuf objects:
+
+    1. Add your group to `cmd/libs/go2idl/go-to-protobuf/protobuf/cmd.go` to `New()` in the `Packages` field
+    2. Run hack/update-generated-protobuf.sh
+
 ### Client (optional):
 
 We are overhauling pkg/client, so this section might be outdated; see [#15730](https://github.com/kubernetes/kubernetes/pull/15730) for how the client package might evolve. Currently, to add your group to the client package, you need to

docs/devel/api-conventions.md

@@ -34,7 +34,7 @@ Documentation for other releases can be found at
 API Conventions
 ===============
 
-Updated: 10/8/2015
+Updated: 4/22/2016
 
 *This document is oriented at users who want a deeper understanding of the Kubernetes
 API structure, and developers wanting to extend the Kubernetes API.  An introduction to
@@ -497,6 +497,8 @@ resourceVersion may be used as a precondition for other operations (e.g., GET, D
 
 APIs may return alternative representations of any resource in response to an Accept header or under alternative endpoints, but the default serialization for input and output of API responses MUST be JSON.
 
+Protobuf serialization of API objects are currently **EXPERIMENTAL** and will change without notice.
+
 All dates should be serialized as RFC3339 strings.
 
 ## Units
@@ -617,13 +619,13 @@ $ curl -v -k -H "Authorization: Bearer WhCDvq4VPpYhrcfmF6ei7V9qlbqTubUc" https:/
 > Host: 10.240.122.184
 > Accept: */*
 > Authorization: Bearer WhCDvq4VPpYhrcfmF6ei7V9qlbqTubUc
-> 
+>
 
 < HTTP/1.1 404 Not Found
 < Content-Type: application/json
 < Date: Wed, 20 May 2015 18:10:42 GMT
 < Content-Length: 232
-< 
+<
 {
   "kind": "Status",
   "apiVersion": "v1",

docs/devel/api_changes.md

@@ -51,6 +51,7 @@ found at [API Conventions](api-conventions.md).
     - [Edit types.go](#edit-typesgo)
   - [Edit validation.go](#edit-validationgo)
   - [Edit version conversions](#edit-version-conversions)
+  - [Generate protobuf objects](#generate-protobuf-objects)
   - [Edit json (un)marshaling code](#edit-json-unmarshaling-code)
   - [Making a new API Group](#making-a-new-api-group)
   - [Update the fuzzer](#update-the-fuzzer)
@@ -472,6 +473,22 @@ generator to create it from scratch.
 Unsurprisingly, adding manually written conversion also requires you to add tests to
 `pkg/api/<version>/conversion_test.go`.
 
+## Generate protobuf objects
+
+For any core API object, we also need to generate the Protobuf IDL and marshallers.
+That generation is done with
+
+```sh
+hack/update-generated-protobuf.sh
+```
+
+The vast majority of objects will not need any consideration when converting
+to protobuf, but be aware that if you depend on a Golang type in the standard
+library there may be additional work requried, although in practice we typically
+use our own equivalents for JSON serialization. The `pkg/api/serialization_test.go`
+will verify that your protobuf serialization preserves all fields - be sure to
+run it several times to ensure there are no incompletely calculated fields.
+
 ## Edit json (un)marshaling code
 
 We are auto-generating code for marshaling and unmarshaling json representation