From 9371ce6150e4a87174e2e5580cdb13e5f260159f Mon Sep 17 00:00:00 2001 From: scawful Date: Sat, 11 Oct 2025 03:03:54 -0400 Subject: [PATCH] docs: update release strategy and command-line flag standardization - Added a section on the "best effort" release strategy for pre-1.0 versions, emphasizing flexibility and transparency in CI/CD workflows. - Introduced a command-line flag standardization decision, adopting the Abseil Flags library for consistent argument parsing across all binaries. - Outlined a migration plan to phase out the legacy flag system, enhancing maintainability and user experience. Benefits: - Improved clarity on release processes and platform availability. - Streamlined command-line argument handling, reducing technical debt and improving user experience. --- docs/B4-git-workflow.md | 18 ++++++++++++++++++ docs/E2-development-guide.md | 23 +++++++++++++++++++++++ 2 files changed, 41 insertions(+) diff --git a/docs/B4-git-workflow.md b/docs/B4-git-workflow.md index 1e44def2..4d6be1b0 100644 --- a/docs/B4-git-workflow.md +++ b/docs/B4-git-workflow.md @@ -28,6 +28,24 @@ --- +## Pre-1.0 Release Strategy: Best Effort Releases + +For all versions prior to 1.0.0, yaze follows a **"best effort"** release strategy. This prioritizes getting working builds to users quickly, even if not all platforms build successfully on the first try. + +### Core Principles +1. **Release Can Proceed with Failed Platforms**: The `release` CI/CD workflow will create a GitHub Release even if one or more platform-specific build jobs (e.g., Windows, Linux, macOS) fail. +2. **Missing Platforms Can Be Added Later**: A failed job for a specific platform can be re-run from the GitHub Actions UI. If it succeeds, the binary artifact will be **automatically added to the existing GitHub Release**. +3. **Transparency is Key**: The release notes will automatically generate a "Platform Availability" report, clearly indicating which platforms succeeded (✅) and which failed (❌), so users know the current status. + +### How It Works in Practice +- The `build-and-package` jobs in the `release.yml` workflow have `continue-on-error: true`. +- The final `create-github-release` job has `if: always()` and uses `softprops/action-gh-release@v2`, which intelligently updates an existing release if the tag already exists. +- If a platform build fails, a developer can investigate the issue and simply re-run the failed job. Upon success, the new binary is uploaded and attached to the release that was already created. + +This strategy provides flexibility and avoids blocking a release for all users due to a transient issue on a single platform. Once the project reaches v1.0.0, this policy will be retired in favor of a stricter approach where all platforms must pass for a release to proceed. + +--- + ## 📚 Full Workflow Reference (Future/Formal) The sections below document the **formal Git Flow model** that yaze will adopt post-1.0 or when the team grows. For now, treat this as aspirational best practices. diff --git a/docs/E2-development-guide.md b/docs/E2-development-guide.md index 2b69d304..4f9a352d 100644 --- a/docs/E2-development-guide.md +++ b/docs/E2-development-guide.md @@ -136,6 +136,29 @@ See [debugging-startup-flags.md](debugging-startup-flags.md) for complete docume For a comprehensive overview of debugging tools and testing strategies, including how to use the logging framework, command-line test runners, and the GUI automation harness for AI agents, please refer to the [Debugging and Testing Guide](E5-debugging-guide.md). +## 5. Command-Line Flag Standardization + +**Decision**: All binaries in the yaze project (`yaze`, `z3ed`, `yaze_test`, etc.) will standardize on the **Abseil Flags** library for command-line argument parsing. + +### Rationale +- **Consistency**: Provides a single, consistent flag system and user experience across all tools. +- **Industry Standard**: Abseil is a battle-tested and well-documented library used extensively by Google. +- **Features**: It provides robust features out-of-the-box, including automatic `--help` generation, type safety, validation, and `--flagfile` support. +- **Reduced Maintenance**: Eliminates the need to maintain multiple custom flag parsers, reducing the project's technical debt. +- **Existing Dependency**: Abseil is already included as a dependency via gRPC, so this adds no new third-party code. + +### Migration Plan +The project will migrate away from the legacy `yaze::util::Flag` system and manual parsing in phases. All new flags should be implemented using `ABSL_FLAG`. + +- **Phase 1 (Complete)**: `z3ed` and `yaze_emu_test` already use Abseil flags. +- **Phase 2 (In Progress)**: The main `yaze` application will be migrated from the custom `util::Flag` system to Abseil flags. +- **Phase 3 (Future)**: The `yaze_test` runner's manual argument parsing will be replaced with Abseil flags. +- **Phase 4 (Cleanup)**: The legacy `util::flag` source files will be removed from the project. + +Developers should refer to the Abseil Flags Guide for documentation on defining, declaring, and accessing flags. + +--- + When working with bitmaps and textures, understand that two memory locations must stay synchronized: 1. **`data_` vector**: C++ std::vector holding pixel data