ksonnet style guide

[jlewi]

We should start a ksonnet style guide to begin capturing best practices and conventions.

Some initial things to document

1. Use camelCase for parameters (option naming inconsistencies #303)
2. Minimize logic in prototype files

A PR creating a markdown doc with the above would be a great starting point. So this would make a good first issue for anyone looking to contribute.

[bhack]

google/jsonnet#118

[jlewi]

Here is a good tutorial on mixins
https://github.com/ksonnet/ksonnet-lib/blob/master/docs/TUTORIAL.md

This could be a pattern we want to make use of.

[ankushagarwal]

Databricks has a very good jsonnet style guide here https://github.com/databricks/jsonnet-style-guide
We should probably stick to that

[jlewi]

Thinking about this more and based on
https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md

I think there are a class of components specifically

• TfJob
• Argo Workflows
• TFServing images
• Seldon models

Where I think it might make more sense to for an existing template/example and then let users modify it. I think this ultimately leads to more readable config than doing complicated things like overrding environment variables and requests limit.

We can support this by using ksonnet prototypes. When we generate a component from a prototype ksonnet copies that prototype into components directory.

So if our prototype defines a complete manifest (as opposed to relying on imports) then ks generate gives users an example which they can then easily customize for their use case.

So for models and jobs I think we should add more prototypes to cover more use cases and rely less on imports.

/cc @lluunn @elsonrodriguez

[jlewi]

Duplicate of #376