Document project goals/non-goals

[jasonkuhrt]

We need to document the newly crystallized project goals leading to e.g. #303 and #304. Users have long brought DX issues to the nexus repo sometimes brought DX issues in for discussion. When applicable those issues may get closed now but we want to do so in a transparent and unsurprising manner. Having docs to point to helps with that.

Also we should update the repo to include a feature-request issue template that includes a prompt for the user to make sure their request doesn't blatantly contradict these project goals. This way we don't waste time triaging wontfix issues and users don't waste time raising them. Of course the user motivation is not wrong, just misplaced. Our doc could mention tools/projects/plugins of interest in the higher order space.

To me this issue is pretty clear but marking as needing discussion in case I missed something CC @tgriesser @Weakky

[tgriesser]

Users have long brought DX issues to the nexus repo and we need to provide clarity when we close those issues as invalid.

Minor point, but I don't know about "long brought"... this project is just about a year since its inception give or take a few days. It's still very early on, and as I see it there's a bit of value in hammock-driven development generally speaking - still mostly taking in the issues and critically thinking about the underlying needs. I do not personally find a need to rush to put out all the "fires", or close all the tickets.

For a concrete example, on issue #53 I have prototyped 2 or 3 possible solutions/implementations locally, but have held off on sharing any because they were hacks and I was wary of building something incompatible with graphql-js. Trying to rush something would have added added more headache/churn in the long run, given the direction extensions are now taking.

Furthermore we should update the repo to include a feature-request issue template that includes a prompt for the user to make sure their request doesn't contradict these project goals. This way we don't waste time triaging wontfix issues and users don't waste time raising them. Of course the user motivation is not wrong, just misplaced. Our doc should be clear about what tools/projects can serve higher order needs/goals.

I think the biggest misconception I have found in talking to folks (and in transferring issues) is the difference between nexus, and nexus-prisma / prisma.

While it has mostly worked well thus-far to be under the umbrella of prisma (and now I guess prisma-labs), I do believe at some point it'd make sense to split nexus back out into a https://github.com/graphql-nexus org, so there's less confusion about the separation between simple (slightly opinionated) GraphQL related abstractions, from layers/abstractions/frameworks that are more convention driven and make use of or extend it.

[jasonkuhrt]

Fixed my phrasing there, that was poorly written.

[jasonkuhrt]

We were tracking workflow related issues before under scope/workflow. There are 9 or so open issues right now. We should probably review them, close out as needed etc.

Perhaps once this issue is resolved, it would be a good time to do that.

scope/workflow

[tgriesser]

Sorry, shouldn't have emphasized your initial wording as I did, I understood the point you were intending to communicate.

I definitely agree that communicating the goals / non-goals for a project is important, and really should have been a priority for me before now. The goals may expand as the project evolves - for instance I foresee at some point making an opinionated wrapper around the http server / execution layer as well, since this is needed for a better contract on plugins which need AST validation to avoid a double traversal.

However being convention-over-configuration for setup/use is intentionally a non-goal, and having that clearly expressed / written out for future issues would be useful.