From 922392a332044d0f44d34988cbb0dd113415646a Mon Sep 17 00:00:00 2001 From: Raymond Jessop Date: Tue, 22 Apr 2025 23:13:39 -0500 Subject: [PATCH] added changelog to readme --- CHANGELOG.md | 33 +++++++++++++++++--------- README.md | 66 ++++++++++++++++++++++++++++------------------------ setup.py | 4 ++-- 3 files changed, 59 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f33f850..3257a77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,23 +2,37 @@ All notable changes to `django_aws_ses` will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. + +## 0.1.2 - 2025-04-22 -## [0.1.2] - 2025-04-22 ### Added + - `CHANGELOG.md` to document version history. +- Clickable table of contents in `README.md` for improved navigation. +- Expanded `README.md` sections for AWS SES configuration and usage, with detailed instructions and AWS documentation links. +- Note in `README.md` Usage section clarifying examples are in a Python console. + +### Changed + +- Updated `README.md` to use `https://yourdomain.com` consistently for example URLs. +- Improved `README.md` formatting for better rendering on PyPI. + +## 0.1.1 - 2025-04-22 -## [0.1.1] - 2025-04-22 ### Added -- Comprehensive installation steps in `README.md`, covering PyPI, and dependency options (`dev`, `dkim`). + +- Comprehensive installation steps in `README.md`, covering PyPI and dependency options (`dev`, `dkim`). - `CONTRIBUTORS.md` to acknowledge ZeeksGeeks team members and their roles. ### Changed -- Updated `README.md` formatting for better rendering on PyPI. + - Incremented version to `0.1.1` to reflect documentation improvements. -## [0.1.0] - 2025-04-15 +## 0.1.0 - 2025-04-15 + ### Added + - Initial release of `django_aws_ses`. - Custom Django email backend for Amazon SES. - Bounce and complaint handling via SNS notifications. @@ -29,9 +43,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Comprehensive test suite covering email sending, bounce/complaint handling, and unsubscribe functionality. ### Notes -- Initial release tested with Django 3.2+ and Python 3.6+. -- Successfully deployed to TestPyPI for validation. -[0.1.0.2]: https://git-vault.zeeksgeeks.com/ZeeksGeeks/django_aws_ses/compare/0.1.0.1...0.1.0.2 -[0.1.0.1]: https://git-vault.zeeksgeeks.com/ZeeksGeeks/django_aws_ses/compare/0.1.0...0.1.0.1 -[0.1.0]: https://git-vault.zeeksgeeks.com/ZeeksGeeks/django_aws_ses/releases/tag/0.1.0 \ No newline at end of file +- Initial release tested with Django 3.2+ and Python 3.6+. +- Successfully deployed to TestPyPI for validation. \ No newline at end of file diff --git a/README.md b/README.md index 62666e3..5ceb05c 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,34 @@ A Django email backend for Amazon Simple Email Service (SES), featuring bounce a ## Table of Contents -- [Features](#features) -- [Installation](#installation) - - [Prerequisites](#prerequisites) - - [Step 1: Install the Package](#step-1-install-the-package) - - [Step 2: Configure Django Settings](#step-2-configure-django-settings) - - [Step 3: Set Up URLs](#step-3-set-up-urls) - - [Step 4: Apply Migrations](#step-4-apply-migrations) - - [Step 5: Configure AWS SES](#step-5-configure-aws-ses) -- [Usage](#usage) - - [Sending a Basic Email](#sending-a-basic-email) - - [Sending HTML Emails](#sending-html-emails) - - [Handling Bounce and Complaint Notifications](#handling-bounce-and-complaint-notifications) - - [Generating Unsubscribe Links](#generating-unsubscribe-links) - - [Viewing SES Statistics](#viewing-ses-statistics52) - - [Debugging and Error Handling](#debugging-and-error-handling) - - [Rate Limiting and Throttling](#rate-limiting-and-throttling) -- [Changelog](#changelog) -- [Contributors](#contributors) -- [License](#license) -- [PyPI Distribution](#pypi-distribution) +- Features +- Installation + - Prerequisites + - Step 1: Install the Package + - Step 2: Configure Django Settings + - Step 3: Set Up URLs + - Step 4: Apply Migrations + - Step 5: Configure AWS SES +- Usage + - Sending a Basic Email + - Sending HTML Emails + - Handling Bounce and Complaint Notifications + - Generating Unsubscribe Links + - Viewing SES Statistics + - Debugging and Error Handling + - Rate Limiting and Throttling +- Changelog +- Contributors +- License +- PyPI Distribution ## Features - Seamless integration with Django’s email framework using a custom SES backend. - Handles AWS SES bounce and complaint notifications via SNS. -- Secure unsubscribe functionality. -- Django Admin dashboard for SES statistics. -- (Optional) Supports DKIM signing, requires `dkimpy`. +- Secure unsubscribe functionality with non-expiring links and GET/POST protection. +- Django Admin dashboard for SES statistics (superusers only). +- Optional DKIM signing support (requires `dkimpy`). ## Installation @@ -141,7 +141,7 @@ This enables endpoints for bounce/complaint handling (`https://yourdomain.com/aw ### Step 4: Apply Migrations -Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`): +Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`, `ComplaintRecord`, `SendRecord`, `AwsSesUserAddon`): ```bash python manage.py migrate @@ -249,7 +249,7 @@ email.send() ### Handling Bounce and Complaint Notifications - Bounce and complaint notifications are processed via the SNS endpoint (`/aws_ses/bounce/`). -- Records are stored in the `BounceRecord` model. +- Records are stored in the `BounceRecord` and `ComplaintRecord` models. - View bounce/complaint data in the Django Admin or SES dashboard (`/aws_ses/status/`). - Configure additional SNS notifications for deliveries in SES console. - Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity.html @@ -270,21 +270,23 @@ unsubscribe_url = addon.unsubscribe_url_generator() - Users clicking the link are redirected to `/aws_ses/unsubscribe///`, which marks them as unsubscribed. - Customize the unsubscribe view or template in `django_aws_ses/templates/django_aws_ses/unsubscribe.html`. -### Viewing SES Statistics Phelps +### Viewing SES Statistics - Access the SES dashboard at `/aws_ses/status/` (superusers only). - Displays bounce rates, complaint rates, and email sending history. -- Uses `BounceRecord` and SES API data for metrics. +- Uses `BounceRecord`, `ComplaintRecord`, and `SendRecord` models for metrics. - Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-metrics.html -### Debugging and Error Handling +### + +System: Debugging and Error Handling - Enable debug logging (see Step 2) to troubleshoot SES errors. - Common issues: - **Unverified email/domain**: Verify in SES console. - **IAM permissions**: Ensure `AmazonSESFullAccess` and `AmazonSNSFullAccess`. - **SNS endpoint errors**: Confirm HTTPS endpoint is publicly accessible. -- Check `BounceRecord` in Django Admin for failed deliveries. +- Check `BounceRecord` and `ComplaintRecord` in Django Admin for failed deliveries. ### Rate Limiting and Throttling @@ -296,7 +298,8 @@ unsubscribe_url = addon.unsubscribe_url_generator() - Docs: https://docs.aws.amazon.com/ses/latest/dg/manage-sending-limits.html ## Changelog -For a detailed list of changes, improvements, and fixes across versions, see [CHANGELOG.md](CHANGELOG.md). + +For a detailed list of changes, improvements, and fixes across versions, see CHANGELOG.md. ## Contributors @@ -311,4 +314,5 @@ This project is licensed under the MIT License. See LICENSE for details. - Install: `pip install django-aws-ses` - Source: https://git-vault.zeeksgeeks.com/public/django_aws_ses - Issues: https://git-vault.zeeksgeeks.com/public/django_aws_ses/issues -- PyPI: https://pypi.org/project/django-aws-ses/ \ No newline at end of file +- PyPI: https://pypi.org/project/django-aws-ses/ +- Changelog: See CHANGELOG.md for version history. \ No newline at end of file diff --git a/setup.py b/setup.py index 26de4d7..0be97fc 100644 --- a/setup.py +++ b/setup.py @@ -5,13 +5,13 @@ with open("README.md", "r", encoding="utf-8") as fh: setup( name="django_aws_ses", - version="0.1.0", + version="0.1.2", author="ZeeksGeeks", author_email="contact@zeeksgeeks.com", description="A Django email backend for Amazon SES with bounce and complaint handling", long_description=long_description, long_description_content_type="text/markdown", - url="https://git-vault.zeeksgeeks.com/public/django_aws_ses", # Replace with your repo or website + url="https://git-vault.zeeksgeeks.com/public/django_aws_ses", packages=find_packages(), include_package_data=True, install_requires=[