Adding first draft of incremental delivery spec artifact

[calvincestari]

Getting something documented that we can always refer back to.

• Copy of the incremental delivery RFC, as of September 2024
• HTTP request headers (TBD)

[martinbonnin]

Very cool! Small preference for just incremental instead of incrementalDelivery for brevity but very cool to have this versioned 🚀

[calvincestari]

Small preference for just incremental instead of incrementalDelivery for brevity ..

Also going back to @martinbonnin's comment above - any preference amongst others too?

[jerelmiller]

@calvincestari @martinbonnin just to make sure I understand, is the incremental vs incrementalDelivery for the name of the spec itself or the header value?

I'm indifferent if you're referring to the spec name, so pick your favorite.

My only preference on the header value is incremental, but only for the reason that I already committed code in Apollo Client/Server using that value 😂 (happy to change it though if that changes as a part of this ask).

[calvincestari]

I was referring to both, or either. Shorter is maybe better?

[BoD]

incremental is 👍 for me

[martinbonnin]

+1 for short parameter

Accept: multipart/mixed;incremental=graphql/incremental/v0.1

[calvincestari]

OK, I've shortened all the things related to incremental vs. "incremental delivery"; header value, filenames, etc. I think this is now ready for formal review and then merging.

[martinbonnin]

Might be worth adding an entry in index.md for better discoverability.

But otherwise very good resource to have around 🤩 , thanks!

[jerelmiller]

Looks great! I'll get the PRs I have open updated 🙂. Thanks!

[calvincestari]

Might be worth adding an entry in index.md for better discoverability.

I've got it in __index__.md but I'm now learning there is index.mx too. 🤦🏻
I'll get it updated there too.

[calvincestari]

I'll get it updated there too.

Done in 33b4062.

[BoD]

🎉

[BoD]

What do y'all think about also adding a v0.0 pointing to a copy of the old spec (the 20220824 one)?

[phryneas]

Or might it be an option to specify this as 0.3, not 0.1? I believe there was another variant implemented between alpha.2 and alpha.9. It might be a good nod at "there was more, we're only documenting this one".

[jerelmiller]

@BoD I was wondering the same thing! I'd appreciate that as well.

@phryneas I'd rather have the versions reflect only the specs we've implemented. Even if graphql.js has had 3 versions, let's keep the versions either v0.0 and v0.1 or even v0.1 for the legacy format and v0.2 for the newer format. No need to add a version for a format we don't implement on our end. I'm impartial to which two version numbers we choose.

[calvincestari]

Sure, I can try add the implemented legacy spec as v0.1 and the latest spec as v0.2. I agree that we probably don't want to archive any interim 'versions' that Apollo did not implement.

[calvincestari]

I don't think we have the same information across both versions:

• v0.1 (legacy):
  • Spec: We've got the detached commit, which is referenced in the Apollo iOS @defer RFC and in a comment by Lenz.
  • RFC: I don't think we have a corresponding reference to the working group RFC at that same point in time though.
• v0.2 (new format):
  • Spec: We don't have a reference to the graphql-spec additions. I think these are spread across a few different PRs at the moment. See #1110, #1124, #1132.
  • RFC: We've referenced the RFC for the most recent commit, which as of now is September 2024.

tl;dr - we're missing opposite pieces of information for each version.

[BoD]

@calvincestari Maybe for the legacy one we could also use the RFC, but the previous commit, which as far as I can tell corresponds to the format we implemented?

[jerelmiller]

@BoD that commit definitely looks like the old format so I think you're correct.

[calvincestari]

v0.1 is now added. I think it could all do with another quick review before merging, just to double-check I've used the right version numbers in the right places.

[jerelmiller]

Looks great! Appreciate you handling this!