Update GitHub Actions and add AI agent guidelines #35
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
secondfry
force-pushed
the
claude/update-artifact-action-011CULiRRhmHHHB1ttQYe7d8
branch
from
b2999ab to
96e6125
Compare
This PR makes three key improvements to the repository's infrastructure
and development standards.
## Summary of Changes
1. **Updated deprecated GitHub Actions**: Upgraded actions/upload-artifact
from v3 to v4 to avoid workflow failures after January 30th, 2025
2. **Fixed Python setup on macOS**: Switched to macos-13 runner to resolve
Python 3.10.19 compatibility issues while maintaining Windows 7 support
3. **Introduced AI agent documentation**: Created comprehensive guidelines
for commit messages and PR descriptions
## Context and Reasoning
### GitHub Actions Deprecation
GitHub is deprecating v3 of actions/upload-artifact starting January 30th,
2025. Workflows using v3 will fail after this date. The v4 API provides
significant performance improvements (up to 98% faster uploads) and continued
support. Updated both Windows and macOS artifact upload steps from v3 to v4.
No breaking changes affect this workflow since each artifact has a unique
name (one of v4's breaking changes is that you can't upload to the same
artifact name multiple times).
### macOS Runner and Python 3.10 Compatibility
Initial workflow failures on macOS were caused by Python 3.10.19 binaries
having a hard dependency on Homebrew's gettext library (libintl.8.dylib),
which isn't available on newer ARM64 macOS runners (macos-latest/macos-14).
Several workarounds were attempted:
- Installing gettext via Homebrew (already installed but not linked)
- Force linking gettext (linking failed in CI environment)
- Upgrading to Python 3.11 (would break Windows 7 support)
The correct solution: Switch from macos-latest to macos-13 (Intel x64).
The Python 3.10.19 gettext issue only affects ARM64 runners; the Intel-based
macos-13 runners work correctly with Python 3.10 out of the box.
Why maintaining Python 3.10 is critical:
- Python 3.10 is the last version to support Windows 7
- Python 3.9+ actively disallows installation on Windows 7
- Project explicitly requires Python 3.10 (Pipfile, README)
- Windows 7 support is important for the Eve Online user community
Also upgraded actions/setup-python from v3 to v5 for better compatibility
and moved checkout before setup-python (recommended order).
### AI Agent Guidelines
The project needed standardized guidelines for AI agents working on the
codebase. There was a tendency for automated commits to lack the "why"
context that makes git history valuable for debugging and understanding
code evolution.
Created two files:
- CLAUDE.md: Entry point that references AGENTS.md
- AGENTS.md: Comprehensive guidelines covering:
* Why commit messages should focus on "why" not "what"
* Benefits of detailed commit messages (understanding past intentions,
helping other engineers, knowledge sharing)
* Examples of bad vs good commit messages
* PR description guidelines following the same principles
* What to include in PR descriptions (summary, context, approach,
trade-offs, testing, risks)
The "why" is often harder to infer than the "what" and requires explicit
documentation. Without it, future developers struggle to understand the
reasoning behind changes when debugging or modifying code.
## Testing
- No code changes that require runtime testing
- GitHub Actions workflow syntax is valid
- Documentation files are properly formatted markdown
- Workflow successfully runs on both windows-latest and macos-13
## Trade-offs and Risks
**Low risk overall**:
- **Artifact action update**: Backward compatible for our use case, no
breaking changes apply
- **macOS runner change**: Using macos-13 (Intel) instead of macos-latest
(ARM64) is acceptable given the Windows 7 requirement. macos-13 is still
actively supported by GitHub Actions
- **Documentation**: Only adds guidelines, doesn't change existing code or
processes
## Benefits
1. **Continued CI/CD operation**: Workflows won't fail after January 30th, 2025
2. **Performance improvement**: Faster artifact uploads in CI pipeline
3. **Platform compatibility**: Maintains Windows 7 support while fixing macOS builds
4. **Better git history**: AI agents will write more meaningful commit messages
5. **Improved PR reviews**: PR descriptions provide better context for reviewers
6. **Knowledge preservation**: Git log becomes a more valuable debugging resource
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
secondfry
force-pushed
the
claude/update-artifact-action-011CULiRRhmHHHB1ttQYe7d8
branch
from
96e6125 to
6dd81ed
Compare
secondfry
deleted the
claude/update-artifact-action-011CULiRRhmHHHB1ttQYe7d8
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR makes three key improvements to the repository's infrastructure and development standards:
Context
GitHub Actions Deprecation
GitHub is deprecating v3 of
actions/upload-artifactstarting January 30th, 2025. Workflows using v3 will fail after this date. The v4 API provides significant performance improvements (up to 98% faster uploads) and continued support.macOS Runner and Python 3.10 Compatibility
Initial workflow failures on macOS were caused by Python 3.10.19 binaries having a hard dependency on Homebrew's gettext library (libintl.8.dylib), which isn't available on newer ARM64 macOS runners (macos-latest/macos-14).
Several workarounds were attempted:
The correct solution: Switch from macos-latest to macos-13 (Intel x64). The Python 3.10.19 gettext issue only affects ARM64 runners; the Intel-based macos-13 runners work correctly with Python 3.10 out of the box.
Why maintaining Python 3.10 is critical:
AI Agent Guidelines
The project needed standardized guidelines for AI agents working on the codebase. There was a tendency for automated commits to lack the "why" context that makes git history valuable for debugging and understanding code evolution.
Approach
Artifact Actions Update
.github/workflows/main.ymlfrom v3 to v4macOS Python Setup Fix
macos-latesttomacos-13(Intel-based runner)actions/setup-pythonfrom v3 to v5 for better compatibilityAI Agent Guidelines Structure
CLAUDE.mdas an entry point that referencesAGENTS.mdAGENTS.mdwith comprehensive guidelines covering:Testing
Risks
Low risk overall:
Benefits
🤖 Generated with Claude Code