Skip to content

Add Grails 8 email guide (v8 prose, snippets, guides.yml)#524

Open
sanjana2505006 wants to merge 1 commit into
apache:masterfrom
sanjana2505006:grails-email-v8-guide
Open

Add Grails 8 email guide (v8 prose, snippets, guides.yml)#524
sanjana2505006 wants to merge 1 commit into
apache:masterfrom
sanjana2505006:grails-email-v8-guide

Conversation

@sanjana2505006

Copy link
Copy Markdown
Contributor

Adds the Grails 8 email guide under guides/grails-email/v8/ (AsciiDoc chapters + vendored snippets) and registers the v8 version in conf/guides.yml with TOC.

Companion to grails-guides/grails-email#1

@jamesfredley jamesfredley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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), and summary.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 on smtpMail.adoc.

Comment thread conf/guides.yml
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.'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Comment thread conf/guides.yml
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'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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>'.

Comment thread conf/guides.yml
toc:
introduction:
title: Introduction
requirements: What you will need

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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[]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

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.

2 participants