Developer Experience

[shaps80]

Developer Experience

• Proposal: [SGQL-170]
• Authors: Shaps
• Status: Draft
• Release: v6

Overview

The current developer experience, particularly for a new library consumer, is less than ideal. While its a great library and simplifies much of the GraphQL experience, it can still be fairly cumbersome and non-intuitive at times.

To address this we’re opening this discussion, not to discuss potential solutions (yet), but rather to discuss pain points and current developer experiences. This should cover areas such as:

• Consumer API
• Header docs
• Documentation
• Error handling
• Limitations in the current release
• etc

Ultimately its important to better understand the current experience from existing users, before we can explore solutions to these problems.

We would appreciate any and all feedback, however critical, to enable us to provide a better experience as a part of our v6 release plans

[shaps80]

As promised: @yonaskolb @tuxi7x
I'll add detail here next week 👍

[shaps80]

To kick things off, @tuxi7x raised a great point regarding the current handling of Alias’ in #152

[tuxi7x]

Thanks @shaps80 !

My biggest pain point is the following (which is already explained in the linked comment):

During app development in debug mode I usually work with mock backends (they are much faster), meaning that there is a static json file that is returned every time when the endpoint is called. Because of the aliases, I could not create a response that is always decoded properly, because the hash generation takes multiple properties into consideration. Maybe this could be solved by setting up a mocked GraphQL backend (like a real GraphQL service, but returning mock data), but so far I had no luck with that.

I also include the same mocked json file to the Xcode project, and use it to test the decoding the response, but that also fails for the same reason.

So for me it would be really ideal to just disable aliases, because I don't have a use case where it is necessary.

[shaps80]

Got it! I completely understand thank you for posting this 👍

[shaps80]

FYI, I've been exploring some potential solutions moving forward (v6) that could solve this entirely by making aliases opt-in – just as you would in a true GraphQL query.

I'll keep this strongly in mind during that exploration/design 👍

[yonaskolb]

One pain point we have is build times for the generated file for a large graph. Our generated file is 74 thousand lines long, and Xcode even has trouble scrolling through it. I've thought about 2 possible solutions for this that are useful in their own right:

1. Generating seperate files instead of 1 large one. This can help build times, especially in incremental builds. There was a great blog post about this recently, but having trouble finding it. Additionally the extra organisation helps when diffing api updates.
2. Optional in/ex-clusion of operations or types. For example I'm working with a spec at the moment that has a lot of admin operations and types in it. Being able to exclude them with some regexes would be very useful.

[shaps80]

Great points! I definitely want to focus less on solutions (just for the moment) but I understand the idea, I had a similar thought myself earlier this week. Even the sample project (GitHub) is around 150K+ lines and takes a LONG time. I realise we generally don't need to reproduce it often but it is a frustration.

The multi-file option I think could potentially work, I considered it myself but there are a few caveats to that approach that need further consideration. Equally inclusion/exclusion lists I've already been thinking about, among others 👍

But again, for now I just want to ensure we're focused on the problems rather than the solutions. Discussing solutions too early tends to lead to solving the wrong thing, because the "problem discussion" is almost _skipped.

But I genuinely appreciate the input so thank you 🙏

[yonaskolb]

Agree with the approach and appreciate the thoughts

[shaps80]

I wanted to contribute my own personal pain points as a (recently) first-time user of the library.

Query building

For me, the query builders feel unintuitive at first. Especially I guess because of the term "builder" having a slightly different meaning in Swift these days. I think part of the reason for this design is to enable the library to automatically construct the "query" and only "select" the appropriate parts.

However at the calcite, I feel like it goes against Swift principles like "clarity at the callsite" and approachability (especially for new users).

I'd love to explore a more resultBuilder approach to this, I don't have a rough design for this yet or even know if this is achievable without some experimentation – so I'm just commenting based on my initial experience when I first tried to use the library.

Error handling

While I understand the history and purpose of using Combine, I feel this is a fairly large barrier in most projects, but even more so here.

While it can provide for some more advanced workflows, I feel like it also over-complicates the simpler (and arguably more common) use-cases.

I'd love to invert this, providing a scalable approach that solves more for the common use-cases, and still allows (even if more involved) for he more advanced workflows.

Improving error propagation would go a long way to enabling the API consumer to implement those more advanced workflows IMO.

Documentation

There's a ton of great documentation from the website, to header docs in this project which is great! However I did find it problematic (and in some cases out-dated) as a first-time user, to understand how to get setup.

I feel we could have a better onboarding experience, as well as ensure header docs – particularly on primary APIs – have far more detail and demo code included, avoiding the need to reach out to another source (README, website, source-code).

Additionally, the README doesn't show even one simple example to help a user quickly get started. They are essentially forced to visit the website AFAICT. This is less than ideal.

Limitations

One of the biggest limitations I hit initially was needing support for multiple queries in a single network call:

query {
  foo
}

query {
  bar
}

I found this particularly difficult to overcome, and while this could just be my (current) limited understanding of the library, I'm sure others would encounter this at some point and have similar concerns.

Again, I won't go into too much solutionising here, but I wonder again if resultBuiler could help here, since we could potentially enable a similar feature that would support multiple queries.

Summary

Overall, my personal findings have led me to believe a larger design update is required that could bring substantial improvements to the consumer API, approachability and likely even the maintainability over time.

[shaps80]

@pokryfka in #177 you raised some great points regarding release notes. As I mentioned in my experience these have not been as valuable in open source as I'd hope. However I do agree they can be useful at times.

To that end, I have a suggestion I'd love to get your input on.

Currently we have an action that runs when we merge branches into main that automatically generates a new release, including notes. My main issue is just that it's a separate page the user has to visit and since most of us manage our deps via SPM, re-visiting a repo is actually uncommon.

What if we update that action to include an update to the README that kind of "pins" the latest release notes near the top of the README.

We could delimit this with markdown dividers making it easy to parse and replace.

This way the README (including in Xcode) would include the latest release notes and therefore any associated links to issues etc.

Would love input on this – I think it could be a nice solution?

[pokryfka]

I cannot speak for others, personally I always check release notes before updating package and IMO its critical to know why/what is changed, if there are new features and breaking changes or bug fixes (e.g. Starscream interface fix) and so on.

How it's done is another question - separate CHANGELOG.md/README.md file is one way to do it.

[shaps80]

Just a quick note, I've broken out the Consumer API portion of this discussion here: #194 for anyone interested 👍