✦
╔════════════════╗
║ 🤝 CONTRIBUTE ║
╠════════════════╣
║ 1. Fork ║
║ 2. Branch ║
║ 3. Code ║
║ 4. PR ║
║ 5. Review ║
║ 6. Merge ║
╚════════════════╝
Contributing
How to contribute to Archon iOS.
Fork → Branch
──────────────
feat/xyz
│
PR #42
│
✓ Review
✓ Merge
Contributing
How to contribute to Archon iOS.
Getting Started
1. Fork the Repository
Click "Fork" on the GitHub repo. Clone your fork locally and follow the Setup guide.
2. Create a Branch
Create a feature branch from
main. Use the naming convention below.3. Make Changes
Write code following the style guide. Add tests for new features. Run the test suite before committing.
4. Submit a PR
Push your branch and open a Pull Request against
main. Fill out the PR template completely.Branch Naming
Use descriptive, lowercase branch names with a type prefix:
feature/add-widget-screen → New feature feature/improve-chat-streaming → Feature improvement fix/crash-on-empty-project → Bug fix fix/token-refresh-race-condition → Bug fix docs/update-setup-guide → Documentation refactor/simplify-viewmodel → Code refactoring test/add-widget-viewmodel-tests → Test additions
Commit Messages
Write clear, concise commit messages following Conventional Commits:
feat: add widget CRUD screen with ViewModel fix: handle token refresh race condition docs: update setup guide with xcodegen instructions test: add WidgetViewModel unit tests refactor: extract common error handling into APIClient
Format
<type>: <description> — lowercase, imperative mood, no period. Max 72 characters for the subject line.Body (optional)
Add a blank line after the subject, then explain what and why (not how). Wrap at 80 characters.
Code Style
Archon follows standard Swift conventions enforced by SwiftLint:
Naming
PascalCase for types, camelCase for properties and methods. Prefix protocols with what they describe (e.g.,
APIClientProtocol), not I or Protocol.Force Unwraps
Never use
! in production code. Use guard let or if let. Force unwraps in tests are acceptable for brevity.Function Length
Keep functions under 40 lines. If a function is longer, extract helper methods or break it into smaller pieces.
Comments
Only add comments for non-obvious logic. Code should be self-documenting through naming. No TODO comments without a linked issue.
SwiftUI Conventions
View Composition
Break complex views into small, composable subviews. Each subview should be under 100 lines.
Modifiers
Apply modifiers in a consistent order: layout → style → behavior → accessibility. Use
.modifier() for reusable modifier sets.Previews
Every view should have a
#Preview macro with a MockAPIClient. This enables instant canvas previews in Xcode.Pull Request Process
1. Fill Out the Template
Include: what changed, why, how to test, and screenshots for UI changes. Link the related issue.
2. Pass CI
All tests must pass. No SwiftLint warnings. No compiler warnings. The GitHub Actions workflow runs automatically on push.
3. Code Review
At least one approval required. Address all review comments. Use "Squash and merge" for clean history.
4. After Merge
Delete your feature branch. Pull the latest
main. If the PR was for a release, the maintainer will handle TestFlight distribution.PR Review Checklist
Reviewer checks:
☐ Tests pass locally
☐ No force unwraps in production code
☐ New code has tests (ViewModel + model decoding)
☐ API changes include MockAPIClient updates
☐ No hardcoded strings — use design tokens
☐ Accessibility labels on interactive elements
☐ Commit messages follow Conventional Commits
Good First Issues
Look for issues tagged good first issue on GitHub. These are scoped to be approachable for new contributors. Common examples:
UI Polish
Spacing adjustments, color updates, adding missing accessibility labels.
Documentation
Improving existing docs, adding code examples, fixing typos.
Test Coverage
Adding tests for existing ViewModels or model decoding paths.
Small Features
Adding a new design token, improving error messages, adding a new filter option.
Questions?
Open a GitHub Discussion for general questions. Use Issues for bug reports and feature requests.