Add Grails 8 email guide (v8 prose, snippets, guides.yml)#524
Add Grails 8 email guide (v8 prose, snippets, guides.yml)#524sanjana2505006 wants to merge 1 commit into
Conversation
jamesfredley
left a comment
There was a problem hiding this comment.
Thanks @sanjana2505006! Reviewed the v8 email guide prose plus conf/guides.yml. The good news first: all 12 TOC keys map to chapter files (no orphans), and every include:: snippet path resolves to a vendored snippet. A few things to address before merge. The publication date is fine, please ignore that one.
Inline comments below cover: the guides.yml TOC syntax and author name, the SMTP config filename mismatch, and the injected == Verify CI heading.
One cross-cutting item that is not line-specific:
-
Typography: please remove em/en dashes (the
—character) throughout. They appear in the subtitle (guides.yml),introduction.adoc(line 1),gettingStarted.adoc(line 17), andsummary.adoc(line 7). Replace them with commas, colons, parentheses, or regular hyphens per project style. -
SMTP config filename (cross-PR): the biggest item is that the mail-config filename must be identical in three places: the sample app (companion PR grails-guides/grails-email#1 currently names it
application-development.yml), the vendored snippet here (application-email.yml), and the prose/caption (application.yml). Please reconcile to a single name across both PRs. Details in the inline comment onsmtpMail.adoc.
| title: 'Send Email and Spock Spring' | ||
| subtitle: 'Learn how to send emails with AWS SES and SendGrid from a Grails app and leverage Spock Spring integration to verify interaction.' | ||
| title: 'Sending Email from a Grails 8 Application (and Testing It)' | ||
| subtitle: 'Send mail over SMTP or through SendGrid / AWS SES, externalize configuration, and verify send interactions with Spock Spring integration tests — without live email.' |
There was a problem hiding this comment.
Typography: this subtitle uses an em dash (— without live email). Project style forbids em/en dashes. Please replace it, for example: ...verify send interactions with Spock Spring integration tests, without live email.
| subtitle: 'Send mail over SMTP or through SendGrid / AWS SES, externalize configuration, and verify send interactions with Spock Spring integration tests — without live email.' | ||
| authors: | ||
| - 'Sergio del Amo' | ||
| - 'Sanjana' |
There was a problem hiding this comment.
Please use a full display name here to match convention. The existing author is Sergio del Amo (full name), so a bare first name Sanjana is inconsistent. Use your full name, e.g. - 'Sanjana <Lastname>'.
| toc: | ||
| introduction: | ||
| title: Introduction | ||
| requirements: What you will need |
There was a problem hiding this comment.
This TOC entry uses the scalar form while every other entry uses the object form with title:. Please make it consistent:
requirements:
title: What you will need| [source,yaml] | ||
| .grails-app/conf/application.yml | ||
| ---- | ||
| include::../snippets/grails-app/conf/application-email.yml[] |
There was a problem hiding this comment.
Snippet filename drift. This include points at application-email.yml, but the caption on the line above says .grails-app/conf/application.yml and the surrounding prose says application.yml, while the companion sample-app PR (grails-guides/grails-email#1) names the file application-development.yml. These must all agree, otherwise the vendored snippet does not correspond to a real file in the sample repo and will drift or break the AsciiDoc build on snippet sync. Please pick one filename and use it consistently in the sample app, the vendored snippet, the listing caption, and the prose.
| To skip ahead, `cd complete` and run the same commands — that tree contains the finished mail services, controller, and integration spec. | ||
|
|
||
| [[cloneAndRun]] | ||
| == Verify CI |
There was a problem hiding this comment.
Chapter titles are supplied by the guide TOC in guides.yml. Injecting a == Verify CI level-2 heading mid-chapter creates an unexpected or duplicate section level in the rendered guide. Please make this normal prose, or demote it to a === subsection if a subsection is intended.
Adds the Grails 8 email guide under
guides/grails-email/v8/(AsciiDoc chapters + vendored snippets) and registers the v8 version inconf/guides.ymlwith TOC.Companion to grails-guides/grails-email#1