Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README suggestion of .sq files in src/main/sqldelight #1212

Merged

Conversation

@handstandsam
Copy link
Contributor

commented Feb 7, 2019

As a first time user of the library I was putting my .sq files in src/main/java/com... and didn't understand why codegen wasn't working. There was a small note in the current README showing an example file path which included src/main/sqldelight, but it wasn't clearly called out as a requirement as a first time user, without custom gradle plugin configuration.

I'm submitting this change in hopes that it will improve the first time experience of using SqlDelight and avoid my 30 minutes of trying to figure out why it wasn't generating sources: https://twitter.com/HandstandSam/status/1093513648885116928

I finally figured it out after finding @AlecStrong's blog post and seeing it as a SQL comment in his examples: https://medium.com/square-corner-blog/announcing-sqldelight-1-0-d482aa408f64

README suggestion of .sq files in src/main/sqldelight
As a first time user of the library I was putting my `.sq` files in `src/main/java/com...` and didn't understand why codegen wasn't working.  There was a small note in the current README showing an example file path which included `src/main/sqldelight`, but it wasn't clearly called out as a requirement as a first time user, without custom gradle plugin configuration.

I'm submitting this change in hopes that it will improve the first time experience of using SqlDelight and avoid my 30 minutes of trying to figure out why it wasn't generating sources: https://twitter.com/HandstandSam/status/1093513648885116928
@@ -6,10 +6,11 @@ SQLDelight generates typesafe APIs from your SQL statements. It compile-time ver
Example
-------

To use SQLDelight, apply the [gradle plugin](https://github.com/square/sqldelight#gradle) and put your SQL statements in a `.sq` file, like
`src/main/sqldelight/com/example/HockeyPlayer.sq`. Typically the first statement creates a table.
To use SQLDelight, apply the [gradle plugin](https://github.com/square/sqldelight#gradle) and put your SQL statements in a `.sq` file in `src/main/sqldelight`. Typically the first statement in the SQL file creates a table.

This comment has been minimized.

Copy link
@JakeWharton

JakeWharton Feb 7, 2019

Collaborator

Should we also explicitly mention that you should use a folder/package structure as well?

This comment has been minimized.

Copy link
@handstandsam

handstandsam Feb 7, 2019

Author Contributor

Yeah. Including where the generated source ends up for people that aren't totally sure how that "magic" works.

I think that is a good sub-section to have, but not critical for providing your "quick start guide" where you just need:

  • dependencies
  • gradle plugin
  • where to put .sq files
  • how to use the generated code in Android/JVM/etc

This comment has been minimized.

Copy link
@handstandsam

handstandsam Feb 7, 2019

Author Contributor

Reading over the docs again, and they are awesome for Kotlin Multiplatform, but I think a "quick start" for Android would suck people in, and the multi-platform would become a later benefit.

All good things to discuss, but not the intent of this PR. Just the small change. Maybe can create an issue for this follow up README work.

This comment has been minimized.

Copy link
@AlecStrong

AlecStrong Feb 7, 2019

Collaborator

yea id be very open to having more targeted getting started guides but keeping the readme more general

This comment has been minimized.

Copy link
@handstandsam

handstandsam Feb 7, 2019

Author Contributor

When/if I have some time I might be able to blog something, but not for at least a week. Sounds like a good plan. Appreciate all the thought/time put into the library. Hopefully can get some good use out of it and can contribute back with some posts about it.

This comment has been minimized.

Copy link
@handstandsam

This comment has been minimized.

Copy link
@AlecStrong

AlecStrong Feb 7, 2019

Collaborator

🎉

@AlecStrong AlecStrong merged commit b3d76cf into cashapp:master Feb 7, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.