Add ADR for choosing a new SDLC #1346
Conversation
Co-authored-by: Greg Dennis <[email protected]>
| extension mechanism. This spec should rarely change. New features would be added | ||
| through additional specifications that define extensions to the "Core Semantics" | ||
| spec. |
There was a problem hiding this comment.
I've made a few comments.
Some are change suggestions, others are thoughts that come to mind while reading it which I wonder if they are worth making notes of (should you keep a list of notes on the SDLC some place. Feel free to create new discussions if a related discussion doesn't exist).
adr/2022-11-stable-spec.md
Outdated
| ## Pros and Cons of the Options | ||
| The biggest benefit is shared between Option 1 and Option 2. Both approaches | ||
| result in a stable spec. This will have benefits for both implementers and | ||
| users. Because of the compatibility requirements, whenever you write a schema, | ||
| you will never need to change it just to keep up with changes to JSON Schema. | ||
| This is also better for implementers because they don't have to maintain | ||
| separate code with different semantics in different versions. They just need to | ||
| code for the current release and they will automatically have support for past | ||
| releases. |
There was a problem hiding this comment.
I think it's worth noting that "past releases" means "from when the first "stable" release is created, not including previous "draft era" versions of JSON Schema".
It's unlikely, but possible, that someone reading this might conclude that they should expect all previous versions, including "draf era" verisons of JSON Schema, should be supported in a single implementation which claims "stable era" support.
| rather than having to wait months or years for the next release to go out. It | ||
| also allows us to iterate faster on unstable features which would allow us to | ||
| get them to a stable state much sooner. For example, we have changes to dynamic | ||
| references that have been agreed upon and ready to go for over a year, but users | ||
| can't benefit from the change until we can get the next full release published. | ||
| With this model, the change could have been made available for over a year now | ||
| and we would have a years worth of feedback on it's use. Having a mutable spec |
There was a problem hiding this comment.
Thinking/spitballing: In such a situation, how would a user be able to determine if an implementation supported the RIGHT version of an unstable feature?
Should we provide guidance that says something like unstable features should be referenced by implementations by the specific commit date of the spec file and tests (if any) they are intending to implement?
That got me thinking further...
If we specified that pre-stable keywords MUST be postfixed with the date of the commit, or stage number, or something, idk, then you make sure users and implementations can differenciate easily between pre-stable and stable versions of that keyword. Although I guess you'd expect to be able to do this with the "release" dialect.
And, I wonder if this is somewhat a moot point if we prevent non-dialect/vocabulary defined keywords from being used.
There was a problem hiding this comment.
This is a bit out of scope for this PR, so let's have this discussion elsewhere.
| The downside of a mutable spec is that it can be more difficult for implementers | ||
| and users to track when changes happen. We will need to be better at | ||
| communicating changes in blog posts or equivalent. |
There was a problem hiding this comment.
I have some automation ideas on this.
Any such concept though would require us to track "latest modified" status of keywords in a structured data file, so automation can be run against such data.
This would add a burden to spec authors, unless unstable features/keywords are written in individual files, and merged into a single spec artifact at workflow time. In which case, changes would be easier to catch, but you still wouldn't know if it was a change requiring implementation change or not unless a human specified such.
There was a problem hiding this comment.
This is a bit out of scope for this PR, but I think I'd argue that this communication is better done by a person than an automation. An automation can't explain why something changed.
There was a problem hiding this comment.
Automation could provide reminders for one of us to post on a change, though.
adr/2022-11-stable-spec.md
Outdated
| with stable features or want to use a new keyword, users have the information | ||
| they need to make that decision. | ||
|
|
||
| The downside of the stability model is that it presents a very high barrier for |
There was a problem hiding this comment.
It's debatable if a high barrier is a downside. If stability is the goal, a high barrier can actually be a benefit.
There was a problem hiding this comment.
I agree. I thought I had addressed that in previous paragraphs, but it seems I only implied it and should be more clear. The high barrier is definitely a benefit, but there's always a trade off. I was trying to address the trade off in this paragraph. I'll try to make it more clear.
There was a problem hiding this comment.
To the point of there being a high barrier, when I decided to create JsonSchema.Net as a replacement for Manatee.Json, there was a LOT of work to do, and the vast majority of it was re-implementing all of the keywords. This high barrier was a serious factor in my consideration of making a new library. (Obviously I decided to do it, but I did have to think about the workload I was taking upon myself.)
It's definitely less of a burden for existing libraries to update than for a new library to be created.
There was a problem hiding this comment.
Right. Although it creates high barriers for spec changes, it actually lowers the barrier for implementers, which is probably worth mentioning as well.
Co-authored-by: Ben Hutton <[email protected]>
There was a problem hiding this comment.
I had apparently started a review when this was first posted but never published it 🤦
The comments I had written have since been addressed. There may be points here I'll want to clarify or debate as we document the actual process, but as documentation of the decision this looks good to me!
Resolves: #1333
Here's the ADR for documenting the reasons for the paradigm shift in how we develop the spec. I included the approach @awwright laid out recently, but I don't see that so much as an alternative as complementary. If we decide we want to work toward that vision, it would fit just fine into the process we have been discussing and have agreement on.