My Notes
3.0 docs issues
unless conflict on multi properties
- Didn’t work in 2.0
- Added in 3.0
- Current docs would force to mark for 3.0, but the 3.0 functionality matches what people expect.
- The 2.0 users are the ones that need to be alerted even though the feature was added in 3.0
In v3, we now support unless conflict on multi properties. I’m struggling with the best way to represent this in the documentation. I could always just drop a versionadded in and say that 3.0 now supports this. The problem with that approach is I feel the intuitive expectation would be that we did support this already, particularly since our documentation doesn’t explicitly state that we don’t. I could add a note to the core documentation stating we don’t support it. Then a versionadded for 3.0 stating that version does support it would make more sense, but I think it could be confusing as a user to read in the 3.0 documentation that we don’t support unless conflict on multi properties and then to have a note saying that we actually do. Leaving the note that we don’t support it out might then leave 2.0 users wondering why it doesn’t work for them.
I would like some way to, in the 2.0 documentation, say that unless conflict does not work on multi properties. That note would just go away in the 3.0 documentation. I don’t think we have a way to do this, do we?
We could use versionchanged, and that’s probably better than versionadded since it is visible for everyone. I feel like this is actually something 2.0 users need to pay more attention to since it’s their expectations that are likely to be unmet by the implementation of the feature. Problem is, the change was made in 3.0, but I think it would be more useful to draw the attention of 2.x users since it doesn’t work as expected in that version. If I use .. versionadded: 3.0, 2.x users are likely to skate over it and miss the fact that in 2.x, unless conflict doesn’t work in this case.
custom access policy errors
- Need to add to synopses for access policies in SDL and DDL reference
- Can only add in a version added
- Options are all bad.
- Duplicate synopsis for 3.0, except with the new feature added?
- Add it to the synopsis and note for 2.0 users that it won’t work for them?
- This would then also be visible for 3.0 users
We added custom error messages to access policies. I’ve added a new section to https://www.edgedb.com/docs/datamodel/access_policies with versionadded, but I’m not sure how to add the syntax for the new feature to the synopses in the SDL and DDL documentation (https://www.edgedb.com/docs/reference/sdl/access_policies and https://www.edgedb.com/docs/reference/ddl/access_policies). The addition would need to be a separate block of some kind and couldn’t sit in context with the rest of the existing synopses. I could have separate complete synopses for 3.0 and put them underneath the 2.x synopses, but it doesn’t seem like a great solution.
I’d love to get your weigh-in on this and the issue that kicked off this thread, @yury. These are some of the issues I was doing a bad job articulating before, but I’m running into some concrete examples now that I’m getting my hands dirty.
new SDL syntax
- New syntax should probably be our preferred syntax (?)
- All SDL examples should use it
- No way to do that currently without breaking earlier docs
- add version-marked code tabs so that 3.0 can display both syntaxes?
The new SDL syntax (replacing -> with : and not requiring property and link) is another one I’m not sure how to handle. (This: https://github.com/edgedb/edgedb/pull/4983)I know there’s been some discussion around the syntax, but if I imagine a world where the new syntax prevails, that leaves the issue of how to integrate it into the documentation. With our current versioning system, we’ll need to leave all the existing arrow syntax in our SDL examples in place throughout the documentation so that it continues to work with our earlier versions. We will sprinkle in blocks or maybe pages documenting the new syntax wherever it makes sense.I’m thinking we are supporting this new syntax because it’s preferable to the arrow syntax (at least in our users’ eyes if not in ours). Maybe I’m wrong on that, but if I’m not, I would want to change all the SDL examples throughout the documentation to use that new preferred syntax (assuming it does come out as the winner in the upcoming syntax deathmatch). I believe we will still support the old syntax, but even so it feels weird to launch a new version with a new improved syntax and document it entirely with examples using the old syntax.If I am wrong and this is just another option on equal footing with the arrow syntax, maybe it’s just a matter of making it possible to mark individual tabs for versions and providing two versions of each SDL example: one in arrow syntax and another in the new syntax? The new syntax tab would be inactive in a version that doesn’t support it.
UUID to object cast
- Adding this cast to the cast table will add to the table for all versions
- Could create another table for 3.x, but then the user is shown both
- What I want is to show the new row and column (“object”) when a user has selected 3.0 but not show it when they have selected 2.0
- Need version block inside description block
json_object_pack
How to add to funcoptable?- Looks like it automatically gets flagged when the description block is flagged.
- “This type doesn’t have its own literal, and instead can be obtained by either casting a value to the :eql:type:
jsontype, or by using the :eql:func:to_jsonfunction:”- We’re going to tell users there are two ways to create a JSON value and then circle back to tell them that there’s one more way in 3.0. Seems misleading.
Support passing tuples as arguments
- “Parameters can only be :ref:
scalars <ref_datamodel_scalar_types>or arrays of scalars. This may seem limiting at first, but in actuality this”- Need to change this sentence to reference tuples of scalars as well, but only for 3.0 docs.
- Just need to note this inline that it is in 3.0
Meeting Notes
- New SDL syntax
- Will go ahead and change to colon syntax
- Moving “extending” to help
- Will support both syntaxes