search

haskell-graphql / graphql-api

Write type-safe GraphQL services in Haskell
BSD 3-Clause "New" or "Revised" License
406 stars 35 forks source link

Module naming #19

Closed teh closed 7 years ago

teh commented 7 years ago

What do you think about this naming? In any case, we have a branch to discuss :)

jml commented 7 years ago

I've been thinking about this a bit.

We need to start from the perspective of the end user. What modules will they need to import? Are there pairs of modules that they'll always need to import together? What modules will they never need to import? What will they probably almost never need to import?

For example, I'm not sure I believe in the separation of Schema and Value. I'm not sure I don't either. I certainly don't know why a user would want them.

This is why I think starting work on something like the servant tutorial (and/or worked examples in the docs) would be a good thing to do now. It will teach us what our structure should be like.

Haddock has a Description field for modules. This shows up in the link to the module on the module index page. I think we should come up with such a description for all of our modules at the same time we come up with names. The description should say why someone should care about that module.

What I want isn't just better module names, but rather a good, clear, and coherent terminology for the whole project. Module names are simply the first terms that our users are exposed to.

Shorter ideas:

I'm sure I had other thoughts, but I cannot recall them now. No doubt there'll be an opportunity :smirk:

teh commented 7 years ago

If you have some time: I added a skeleton tutorial can you test whether you can build it? I don't know how people use pip/python these days so you might have to install some tools.

jml commented 7 years ago

Will do as soon as I may. Got distracted cleaning up imports and really do need to get back to work.

Further thoughts on naming:

On Fri, 16 Dec 2016 at 14:03 teh notifications@github.com wrote:

If you have some time: I added a skeleton tutorial can you test whether you can build it? I don't know how people use pip/python these days so you might have to install some tools.

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/jml/graphql-api/pull/19#issuecomment-267600482, or mute the thread https://github.com/notifications/unsubscribe-auth/AAHq6mUdju25TxLZofq-jNsr2IesFopoks5rIppEgaJpZM4LPGuv .

jml commented 7 years ago

Can confirm that I can build sphinx docs, but cannot build the tutorial docs.

I've sent an email to the servant mailing list asking how they do it: https://groups.google.com/forum/#!topic/haskell-servant/qxNBq11adBI

As a way forward, I think we should:

jml commented 7 years ago

Also docs/build/ needs to be added to .gitignore

teh commented 7 years ago

rebased, docs/build/ should be in a gitignore already - not working for you?

jml commented 7 years ago

rebased, docs/build/ should be in a gitignore already - not working for you?

Nope.

jml@wit:~/src/graphql-api (module-naming) (0)
$ git rev-parse HEAD
b80ebaa75ddfd1988632cb5bcd880ab3f8eb5372
jml@wit:~/src/graphql-api (module-naming) (0)
$ cat .gitignore 
/.stack-work
jml@wit:~/src/graphql-api (module-naming) (0)
$ git status
On branch module-naming
Your branch is up-to-date with 'origin/module-naming'.
nothing to commit, working tree clean
teh commented 7 years ago

re .gitignore, see: https://github.com/jml/graphql-api/pull/19/files#diff-14b597b3f3e040934bdb59aa959344a7 - it's not the top-level .gitignore

jml commented 7 years ago

re .gitignore, see: https://github.com/jml/graphql-api/pull/19/files#diff-14b597b3f3e040934bdb59aa959344a7 - it's not the top-level .gitignore

Oops, my bad. Works for me now.