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

@handstandsam handstandsam 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

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.
Copy link
Member

@JakeWharton JakeWharton Feb 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@handstandsam handstandsam Feb 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@handstandsam handstandsam Feb 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

@AlecStrong AlecStrong Feb 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@handstandsam handstandsam Feb 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@handstandsam handstandsam Feb 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Collaborator

@AlecStrong AlecStrong Feb 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎉

@AlecStrong AlecStrong merged commit b3d76cf into cashapp:master Feb 7, 2019
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants