Skip to content

docs: book-forms - Document operations, consent and release evidence #215

Open

Description

@ashleyshaw

Documentation Update Summary

Document Netlify capture and separate Brevo DOI operations, ownership, consent, retention and release evidence. M reflects two systems and operating decisions, not duration.

Linked Stories/Tasks/PRs/Epic

Parent: #16. Project: This One Time on Acid — book. Implementation/QA dependencies; no PR linked.

Milestones & Timeline

No milestone, cycle, due date or release date requested.

What documentation is needed?

Separate approved policy, proposed architecture, verified configuration, observed evidence and unresolved decisions. Reuse #210 for contact storage/confirmation, About contact and contact thank-you; #213/324 for newsletter thank-you/operations. Page visits alone are not conversions; event/privacy definitions remain unresolved.

Proposed docs/netlify-forms.md: three schemas/five capture routes/pathname, effective build/toolchain/configuration/publish/fallback, detection/redeployment/post-processing/output inspection, parity/testing/historical baseline, Verified/Spam/honeypot troubleshooting, capture limits, approved monitoring/notifications, retention/export and secure CSV/email handling. No routine export or deletion is authorised; reconcile handling with DEC-003 and obtain separate approval.

Document Brevo /newsletter embed, authorised owner/non-secret form/list refs, current free-plan/sender prerequisites, consent/privacy/DOI initial-pending-versus-confirmed/unsubscribe, troubleshooting and independent ownership. No Netlify-to-marketing enrolment, fourth detector/Function bridge/client API secrets.

  • Agree monitoring owner/contact and waitlist scope; recipients before configuration.
  • Forms → Submission notifications → Add notification: supported email/webhook only for approved scope; prefer scoped contact initially, not all signups to all recipients.
  • Fresh controlled delivery and reply behaviour using submitted email verified.
  • Do not call operator notifications customer acknowledgements; no unapproved webhook/credentials/external automation.
  • Confirm purpose-specific responsibilities and secure handling; preserve approved Ash-only manuscript-entry operations.
  • Add approved Unreleased entry to root CHANGELOG.md; resolve CONTRIBUTING's differing src/app/CHANGELOG.md reference rather than silently substitute.
  • Attach deployed SHA/tests/operator/provider evidence and blockers.
  • Record entire-short-website-edition entitlement after verified email, including direct chapters; receipt alone grants none. Reader route, verification/returning access, provider, retention/deletion and offline reconciliation remain unresolved under DEC-001–003. Ash-only manuscript-entry operations are approved policy, not verified permissions or authority over contact/newsletter/telemetry.

Why is this documentation important?

Prevent frontend success being mistaken for stored receipt, secure draft access or confirmed newsletter membership; make monitoring, consent, unsubscribe and personal-data handling operationally clear.

Acceptance Criteria

  • Docs match verified deployed configuration/contracts/provider settings.
  • Monitoring/recipient scope/delivery, newsletter consent and unsubscribe evidence recorded.
  • Purpose-specific retention, deletion, permissions and responsibilities are approved and evidenced; unresolved decisions remain blockers.
  • Capture exclusions/reader decision clear; no unsupported implementation claims.
  • Changelog/release evidence and blockers linked.
  • Documentation is clear, accurate, and up-to-date
  • Includes code examples/screenshots if applicable
  • Documentation is accessible and easy to find
  • Changelog entry prepared for PR if user-facing update
  • PR uses correct branch prefix (docs/)
  • PR description updated with relevant details
  • Changelog entry prepared for PR (if applicable)
  • Labels/types match org standards

Additional Context

AGENTS.md, notifications, submissions, Brevo signup, pricing. Dependencies: final evidence, authorised operators, consent/privacy, recipients and retention decisions. No account/DNS/campaign changes authorised by issue creation.

LightSpeed Documentation ordered defaults retained: meta:no-changelog despite changelog checklist and status:needs-triage despite Backlog are explicitly approved conflicts, not permission to alter taxonomy/templates. Unassigned, no dates/delegate/cycle/milestone.


Definition of Ready (DoR)

  • Documentation need is clear and well-defined
  • Related docs/issues or files linked
  • Acceptance criteria listed
  • Estimate added if relevant
  • Milestone/release assigned (if applicable)

Definition of Done (DoD)

  • Documentation meets org standards and guidelines
  • Changelog entry prepared for PR (CHANGELOG.md)
  • Documentation reviewed for clarity and accessibility
  • Screenshots/code examples included if relevant
  • PR uses correct branch prefix (docs/)
  • PR uses the correct PR template based on type:docs PR label or linked issue type or linked issue type:docs label
  • Branch deleted after merge
  • Linked issue(s) updated with latest status and closed after merge,
  • The related epic should not be closed, instead updated with a comment to reflect the closed issue

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Fields

Priority

None yet

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions