Missing keys in file reference? (replicas and labels)

[cdrage]

Bit confused by the file reference here:
https://github.com/kedgeproject/kedge/blob/master/docs/file-reference.md

I see that we have "replicas" and "labels" but it does not indicate it's not yet implement nor it's in the example.

[cdrage]

Another thing to note is "ingresses" is in the full example at the bottom, but not in the reference example at the top.

[kadel]

I see that we have "replicas" and "labels" but it does not indicate it's not yet implement nor it's in the example.

not yet implemented? both 'replicas' and 'labels ' are implemented

[surajssd]

Another thing to note is "ingresses" is in the full example at the bottom, but not in the reference example at the top.

To keep example shorter we only added the key endpoint which also generates the default ingress, so it is not shown there.

ingresses root level field is for people who wanna specify ingress by themselves.

[cdrage]

@kadel Ah okay, it's a docs issue then. There's no example on either the bottom or the top that shows how it's implemented in a full file.

[cdrage]

@surajssd Okay, we should show how we use it then in an example.

[kadel]

I'm not a big fan of showing everything in one file, to be honest, it looks scary, it's hard to read, and I doubt that any application will ever use every feature there is.

[pradeepto]

I'm not a big fan of showing everything in one file, to be honest, it looks scary, it's hard to read, and I doubt that any application will ever use every feature there is.

I am confused about this because this is supposed to be a file reference. Should the example not have every feature? Maybe we need a middle path.

Ok, how about having smaller examples at "key" level? Not necessarily for all keys but some keys that we think are important. Often you see such examples in API docs where small focused snippet (partial code) are provided for certain methods showcasing usage of that method.

[kadel]

👍 for multiple small examples highlighting features that are documented in given section

[surajssd]

@cdrage it is shown here: https://github.com/kedgeproject/kedge/tree/master/examples/ingress

[cdrage]

@kadel @surajssd Okay. Smaller examples 👍 but let's get some examples into the file reference doc, not putting docs in the examples folder.

[pradeepto]

File reference should have snippets only and not whole examples or it becomes just a long file that people will get lost in. Of course, in a certain case where it is important to show the whole example, we do that. Use your best judgement.

[pradeepto]

And we should definitely have the examples folder, it is a great learning resource.

[pradeepto]

@cdrage @kadel @surajssd @containscafeine What is the resolution here? And what would be the action items?

[cdrage]

@pradeepto I believe we can resolve this in #136 as well as doing minor updates to the file reference doc to avoid any confusion in regards to missing keys.

[cdrage]

Now that http://kedgeproject.org/file-reference/ has been created, it's quite clear that you are able to "extend" the Kedge file with Pod concepts, and thus, replicas is clearly documented. Closing this issue.