From 925705b16bba87c830c74b25533cc49ff59d0b84 Mon Sep 17 00:00:00 2001 From: "Dan Ryan (GitHub Noreply Key)" Date: Tue, 18 Nov 2025 11:44:17 -0500 Subject: [PATCH 1/3] v4.4.3: Add breaking change warning to update notifications - Updated version to 4.4.3 in d3ploy.py and pyproject.toml - Added prominent warning in update notifications about upcoming v5.0 changes - Added AGENTS.md and ROADMAP.md for conversion planning This patch release warns existing users about upcoming breaking changes in the planned Briefcase console app conversion. --- AGENTS.md | 114 +++++++++++++++++++++++++ ROADMAP.md | 218 +++++++++++++++++++++++++++++++++++++++++++++++ d3ploy/d3ploy.py | 8 +- pyproject.toml | 2 +- 4 files changed, 339 insertions(+), 3 deletions(-) create mode 100644 AGENTS.md create mode 100644 ROADMAP.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..adc709f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,114 @@ +# AGENTS.md - Development Preferences for d3ploy Briefcase Conversion + +This file captures preferences and guidelines for AI agents working on the d3ploy project, specifically for converting it to a Briefcase console application. + +## Project Context + +- **Current State**: Python CLI tool that syncs files to AWS S3 with multiple environment support +- **Goal**: Convert to standalone Briefcase console app for distribution without dependency management +- **Repository**: + +## Questions for Project Owner + +Please answer the following questions to help guide the development process: + +### 1. **Target Platforms & Distribution** + +- ✅ **Platforms**: All three (macOS, Windows, Linux) +- ✅ **Distribution**: GitHub releases + PyPI distribution +- ❓ **Architecture requirements**: Intel, ARM, universal binaries? + +### 2. **User Experience & Interface** + +- ✅ **Breaking changes allowed**: Yes, if they make sense +- ✅ **New features**: Will be added in future releases after this conversion +- ✅ **Interface improvements**: Open to modernizing the CLI experience + +### 3. **Configuration & Data** + +- ✅ **Config files**: Support both `d3ploy.json` and `.d3ploy.json` in project directory +- ✅ **App data**: Move cache, logs, temp files to standard app data locations +- ✅ **Configuration priority**: CLI flags > environment variables > config file > defaults + +### 4. **Dependencies & Bundling** + +- ✅ **Minimize dependencies**: Replace colorama with first-party code +- ✅ **Use Textual**: Use instead of colorama + tqdm +- ✅ **boto3**: Keep for now, replace with custom AWS library in future +- ✅ **Final bundle preference**: Textual for modern TUI experience + +### 5. **Development & Testing** + +- ✅ **Unified approach**: Pip package distributes Briefcase binary (like ruff/uv) +- ✅ **Single codebase**: One version, different packaging approach +- ✅ **Distribution**: PyPI wheels with binaries + GitHub releases + +### 6. **Maintenance & Updates** + +- ✅ **Update source**: Continue using PyPI as version source of truth +- ✅ **Update notifications**: Follow Textual interface patterns +- ✅ **Breaking changes**: Release patch version warning about upcoming changes +- ✅ **Config migration**: Auto-detect and migrate old config versions +- ✅ **Config versioning**: Add version property to new config structure + +### 7. **Code Organization** + +- ✅ **Refactoring allowed**: Yes, prioritize maintainability and testability +- ✅ **Modular structure**: Break apart large d3ploy.py into focused modules +- ✅ **Separation of concerns**: UI, AWS ops, config, file operations in separate modules +- ✅ **Briefcase compatibility**: Structure code to work well with Briefcase and Textual + +--- + +## Development Guidelines + +Based on the responses above, here are the guidelines for this conversion: + +### Architecture & Code Organization + +- **Modular design**: Refactor the monolithic `d3ploy.py` into focused modules: + - `config/` - Configuration loading, validation, and migration + - `aws/` - S3 and CloudFront operations (keeping boto3 for now) + - `ui/` - Textual-based interface components + - `sync/` - File synchronization logic + - `core/` - Main application logic and coordination +- **Testability**: Design for easy unit testing of individual components +- **Briefcase structure**: Follow Briefcase app conventions for entry points and packaging + +### User Interface & Experience + +- **Textual integration**: Replace colorama + tqdm with Textual for modern TUI experience +- **Breaking changes**: Document and implement sensible improvements to CLI +- **Error handling**: Improve error messages and user feedback with Textual's capabilities +- **Progress indication**: Use Textual's rich progress components + +### Configuration & Data Management + +- **Config files**: Support both `d3ploy.json` and `.d3ploy.json` in project directory +- **Config versioning**: Add `version` property to config structure for migration +- **Auto-migration**: Detect and automatically upgrade old config formats +- **Priority order**: CLI flags > environment variables > config file > defaults +- **App data**: Move cache, logs, temp files to platform-standard app data directories + +### Dependencies & Bundling + +- **Textual**: Primary UI framework replacing colorama and tqdm +- **boto3**: Keep for now, plan future replacement with custom AWS library +- **Minimize deps**: Replace other dependencies where practical +- **Bundle size**: Optimize for reasonable size while maintaining functionality + +### Distribution & Updates + +- **Unified approach**: Single codebase, PyPI distributes Briefcase binaries +- **Platform support**: macOS, Windows, Linux binaries +- **GitHub releases**: Direct binary downloads as alternative to PyPI +- **Update checking**: Continue using PyPI as source of truth +- **Breaking change warning**: Release patch version before major changes + +### Release Process + +- **Semantic versioning**: Continue current approach +- **Warning release**: Issue patch with breaking change notification +- **Config migration**: Ensure smooth transition for existing users +- **Testing**: Platform-specific testing for binary distributions +- **CI/CD**: Build binaries for all platforms in automated pipeline diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..a644e81 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,218 @@ +# D3ploy Briefcase Conversion Roadmap + +This roadmap outlines the complete conversion of d3ploy from a traditional Python package to a Briefcase console application with Textual interface. + +## Phase 1: Breaking Change Warning Release + +### 1.1 Current Version Patch Release + +- [x] Update update notification text to warn about upcoming major changes +- [x] Test warning message displays correctly +- [ ] Release patch version (4.4.3) to PyPI +- [ ] Monitor user feedback and questions +- [ ] Document migration timeline and what's changing + +### 1.2 User Communication + +- [ ] Update GitHub README with migration notice +- [ ] Create GitHub issue/discussion about upcoming changes +- [ ] Provide clear timeline for new version +- [ ] Document what will break and how to prepare + +## Phase 2: Project Setup & Foundation + +### 2.1 Briefcase Configuration + +- [x] Create initial `briefcase.toml` configuration +- [ ] Install Briefcase and verify setup +- [ ] Test basic Briefcase build process +- [ ] Configure platform-specific settings + +### 2.2 Dependencies & Environment + +- [ ] Add Textual to dependencies +- [ ] Update `pyproject.toml` with new dependency structure +- [ ] Remove colorama and tqdm from requirements +- [ ] Test dependency resolution + +### 2.3 Project Structure Planning + +- [ ] Design new modular package structure +- [ ] Plan module responsibilities and interfaces +- [ ] Create placeholder modules and **init**.py files + +## Phase 2: Code Refactoring & Modularization + +### 2.1 Configuration System + +- [ ] Create `d3ploy/config/` module +- [ ] Implement config versioning system +- [ ] Add support for both `d3ploy.json` and `.d3ploy.json` +- [ ] Implement environment variable support +- [ ] Create config migration logic for old formats +- [ ] Add priority system: CLI flags > env vars > config file > defaults + +### 2.2 AWS Operations Module + +- [ ] Create `d3ploy/aws/` module +- [ ] Extract S3 operations from main file +- [ ] Extract CloudFront operations from main file +- [ ] Maintain boto3 compatibility +- [ ] Add proper error handling and retries + +### 2.3 File Synchronization Module + +- [ ] Create `d3ploy/sync/` module +- [ ] Extract file discovery logic +- [ ] Extract upload/download logic +- [ ] Extract deletion logic +- [ ] Implement pathspec-based filtering +- [ ] Add gitignore support + +### 2.4 Core Application Logic + +- [ ] Create `d3ploy/core/` module +- [ ] Extract main application coordination logic +- [ ] Implement proper signal handling +- [ ] Add graceful shutdown mechanisms + +## Phase 3: Textual Interface Implementation + +### 3.1 Basic UI Components + +- [ ] Create `d3ploy/ui/` module +- [ ] Design Textual application structure +- [ ] Implement progress bars to replace tqdm +- [ ] Create status display components +- [ ] Add colored output to replace colorama + +### 3.2 Interactive Features + +- [ ] Implement confirmation dialogs +- [ ] Add real-time progress updates +- [ ] Create error display components +- [ ] Add update notification UI + +### 3.3 CLI Integration + +- [ ] Maintain command-line argument compatibility +- [ ] Integrate Textual with argparse +- [ ] Implement quiet mode for automated usage +- [ ] Add proper exit codes and error handling + +## Phase 4: Data Management & Standards + +### 4.1 App Data Directories + +- [ ] Implement platform-specific app data paths +- [ ] Move cache files to standard locations +- [ ] Move log files to standard locations +- [ ] Move temporary files to standard locations +- [ ] Maintain backward compatibility for existing users + +### 4.2 Update System Enhancement + +- [ ] Modify update checker for new architecture +- [ ] Implement Textual-based update notifications +- [ ] Add breaking change warning system +- [ ] Test PyPI version checking + +## Phase 5: Testing & Quality Assurance + +### 5.1 Unit Testing + +- [ ] Create tests for config module +- [ ] Create tests for AWS operations module +- [ ] Create tests for sync module +- [ ] Create tests for core logic +- [ ] Create tests for UI components (where applicable) +- [ ] Ensure 100% test coverage maintenance + +### 5.2 Integration Testing + +- [ ] Test Briefcase build process +- [ ] Test cross-platform compatibility +- [ ] Test config migration scenarios +- [ ] Test environment variable handling +- [ ] Test real AWS operations (with mocking) + +### 5.3 Performance Testing + +- [ ] Benchmark new vs old performance +- [ ] Test memory usage of bundled app +- [ ] Test startup time +- [ ] Test large file synchronization + +## Phase 6: Briefcase Build & Distribution + +### 6.1 Build Configuration + +- [ ] Finalize Briefcase configuration for all platforms +- [ ] Configure app icons and metadata +- [ ] Set up code signing (if needed) +- [ ] Test builds on all target platforms + +### 6.2 Distribution Setup + +- [ ] Configure GitHub Actions for automated builds +- [ ] Set up PyPI wheel distribution with binaries +- [ ] Configure GitHub releases for direct downloads +- [ ] Test installation from both sources + +### 6.3 Documentation Updates + +- [ ] Update README.md for new installation methods +- [ ] Update configuration documentation +- [ ] Add migration guide from old version +- [ ] Document new features and breaking changes + +## Phase 7: Release Preparation + +### 7.1 Breaking Change Warning Release + +- [ ] Create patch release (e.g., 4.4.3) with breaking change warning +- [ ] Update existing users about upcoming changes +- [ ] Provide timeline for new version release +- [ ] Ensure clear migration path documentation + +### 7.2 Final Release + +- [ ] Complete all testing and validation +- [ ] Prepare release notes with full changelog +- [ ] Tag new major version release +- [ ] Deploy to PyPI and GitHub releases +- [ ] Monitor for issues and provide support + +## Phase 8: Post-Release + +### 8.1 User Support + +- [ ] Monitor for bug reports +- [ ] Help users with migration issues +- [ ] Address any platform-specific problems +- [ ] Collect feedback for future improvements + +### 8.2 Future Planning + +- [ ] Plan custom AWS library to replace boto3 +- [ ] Evaluate additional Textual features to implement +- [ ] Consider new features for next release +- [ ] Document lessons learned + +--- + +## Current Status: Phase 1.1 - Breaking Change Warning Release + +**Next Steps:** + +1. Update update notification text with breaking change warning +2. Test the warning message +3. Release patch version 4.4.3 to PyPI + +**Blockers:** None currently identified + +**Notes:** + +- Keep AGENTS.md updated with any preference changes +- Each phase should be tested before moving to the next +- Breaking change warning gives users time to prepare diff --git a/d3ploy/d3ploy.py b/d3ploy/d3ploy.py index 643f0ed..e62c02b 100755 --- a/d3ploy/d3ploy.py +++ b/d3ploy/d3ploy.py @@ -24,7 +24,7 @@ from colorama import init as colorama_init from tqdm import tqdm -VERSION = "4.4.2" +VERSION = "4.4.3" VALID_ACLS = [ "private", @@ -183,7 +183,11 @@ def check_for_updates( f"There has been an update for d3ploy. Version " f"{pypi_version} is now available.\n" f"Please see https://github.com/dryan/d3ploy or run " - f"`pip install --upgrade d3ploy`." + f"`pip install --upgrade d3ploy`.\n\n" + f"⚠️ IMPORTANT: A major update with breaking changes is coming soon! ⚠️\n" + f"The next major version will include significant improvements but may\n" + f"require config file updates. Please check the GitHub repository for\n" + f"migration guidance before upgrading to version 5.0+." ), color=colorama.Fore.YELLOW, ) diff --git a/pyproject.toml b/pyproject.toml index 80f9c51..0f45b16 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "d3ploy" -version = "4.4.2" +version = "4.4.3" description = "Easily deploy to S3 with multiple environment support." authors = [ {name = "dryan", email = "dryan@users.noreply.github.com"}, From 826e4e0e819815dbeb109fe7ba2df5b69c85e04d Mon Sep 17 00:00:00 2001 From: "Dan Ryan (GitHub Noreply Key)" Date: Tue, 18 Nov 2025 11:45:53 -0500 Subject: [PATCH 2/3] Update release process documentation in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added correct Git workflow: PR → merge → tag → GitHub Actions release --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index adc709f..942f206 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,6 +108,8 @@ Based on the responses above, here are the guidelines for this conversion: ### Release Process - **Semantic versioning**: Continue current approach +- **Git workflow**: Create PR → merge to main → push git tag → GitHub Actions triggers release +- **PyPI automation**: GitHub Actions handles PyPI publishing on tag push - **Warning release**: Issue patch with breaking change notification - **Config migration**: Ensure smooth transition for existing users - **Testing**: Platform-specific testing for binary distributions From 4b0401bc278ccfb6bc68aefa2f170ea98a4c9818 Mon Sep 17 00:00:00 2001 From: "Dan Ryan (GitHub Noreply Key)" Date: Tue, 18 Nov 2025 11:46:30 -0500 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20Add=20gitmoji=20requirement?= =?UTF-8?q?=20to=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document that all commits should use gitmoji for consistency --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 942f206..ccd45c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,6 +110,7 @@ Based on the responses above, here are the guidelines for this conversion: - **Semantic versioning**: Continue current approach - **Git workflow**: Create PR → merge to main → push git tag → GitHub Actions triggers release - **PyPI automation**: GitHub Actions handles PyPI publishing on tag push +- **Gitmoji**: Always use gitmoji for commit messages - **Warning release**: Issue patch with breaking change notification - **Config migration**: Ensure smooth transition for existing users - **Testing**: Platform-specific testing for binary distributions