Need some text (primer?) about how we see people using doc view#463
Conversation
4aef7c3 to
19937c5
Compare
| Writing up a registry by hand can be a great way of getting the idea, but it can | ||
| get tedious quickly. This is when you want to use the API server. | ||
|
|
||
| ### Static File Server |
There was a problem hiding this comment.
It seems like there's a step that's missing: multiple files on disk, but not a "file server".
While having one large json file is always an option, don't we think that people will find this tedious to manage and instead create individual files for each Resource in a dir structure that matches the xReg URL structure.
There was a problem hiding this comment.
This would then also lead into a discussion about how the Resource file on disk itself may not contain anything in it - all data is in the Version. This is actually something we may want to discuss as I think this might confuse or bother people. If I'm using "files on disk" then I would expect "something" at the Resource level and not be required to find the default version. BUT, our ?doc flag purposely hides the duplicate info at the Resource level - which is why the file is empty in this "files on disk" case. I'm starting to wonder if we should rethink that decision, and perhaps the Resource (on export - ?doc) should still include the default version attributes due to the usability concern.
jskeet
left a comment
jskeet
left a comment
There was a problem hiding this comment.
A few comments, but I admit I got a bit lost in the discussion of shadowing. I do wonder how many readers are going to want/need that information.
|
|
||
| A registry document, whether a single [file](#71-file) or the root of a | ||
| [static file server](#72-static-file-server) layout, is meant to be loaded into | ||
| an application as a local, in-memory registry. While a document technically |
There was a problem hiding this comment.
What kind of application are we talking about here? I wouldn't expect most client applications to want to fetch "the registry".
If this is more about this being possible, I think some rewording is required.
There was a problem hiding this comment.
We have a lot of file-based examples where "the registry" is that one file.
|
Conditionally approved on 5/2 call - will merge once comments are addressed |
| - [10.4. Deleting entities](#104-deleting-entities) | ||
| - [10.5. Detection of Referenced Resources](#105-detection-of-referenced-resources) | ||
| - [10.6. Shared/Referenced Resources](#106-sharedreferenced-resources) | ||
| - [Default Version and Maximum Versions](#default-version-and-maximum-versions) |
There was a problem hiding this comment.
this indentation doesn't seem right, and the html rendering looks odd
|
|
||
| #### 8.3.2. Shadowing | ||
|
|
||
| Federation in xRegistry is intended to be built on *shadowing*: an application's |
There was a problem hiding this comment.
This is an interesting section. I don’t remember discussing this in the meetings, unless it was when I wasn’t around. The way it’s currently framed is quite opinionated, which is why I’m asking: is this something we decided, and if so, is that represented in the rest of the spec? If not, should it really be framed this “pressing”?
|
@clemensv a rebase is needed |
c2a5b8e to
a586c9f
Compare
|
@clemensv since your other PR touched the primer, a rebase is needed |
Fixes xregistry#386 Signed-off-by: Clemens Vasters <clemensv@microsoft.com>
Signed-off-by: Clemens Vasters <clemens@vasters.com>
Signed-off-by: Clemens Vasters <clemens@vasters.com>
a586c9f to
c6213b8
Compare
|
@clemensv CI is unhappy |
Update 4 cross-references to match the section-numbered slugs (xregistry#7-representations, xregistry#9-possible-use-cases x2, #10612-singleversionroot-policy-enforcement), fixing the failing links check. Signed-off-by: Clemens Vasters <clemensv@microsoft.com> Signed-off-by: Doug Davis <duglin@gmail.com>
c6213b8 to
769f7f5
Compare
4 participants
Fixes #386
FIxes #394
Fixes #451
Ths is a section about files vs directories vs APIs and federation.