Skip to content

Improve AGENTS guide #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TinyTb wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve AGENTS guide #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 52 additions & 33 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,56 @@
This file is a stub and is not yet complete.

You should edit, add, and improve it!

# Dependency Management

## Dependency Manager

The project uses **Swift Package Manager (SwiftPM)** for managing dependencies. SwiftPM is Apple's native package manager, and it is integrated with the Xcode ecosystem.

### Overview of SwiftPM Usage
Each module in the project appears to be its own Swift package, with a `Package.swift` file located in the `Packages` directory. This allows the project to manage its dependencies through these modular packages.

## List of Packages
# IceCubesApp Development Guide

This document provides notes for contributors and automated agents working in this repository.

## Project Overview
IceCubesApp is an open-source Mastodon client written entirely in SwiftUI. The repo contains the main `IceCubesApp` Xcode project plus a set of Swift packages under `Packages/` that implement most of the functionality.

## Repository Layout
- `IceCubesApp` – main application target
- `IceCubesShareExtension`, `IceCubesActionExtension`, `IceCubesNotifications`, `IceCubesAppIntents`, `IceCubesAppWidgetsExtension` – extra targets and extensions
- `Packages/` – independent Swift packages listed below

### Packages
1. **Account** – user profile and account management
2. **AppAccount** – multi-account support
3. **Conversations** – direct messages
4. **DesignSystem** – shared UI components and theming
5. **Env** – global environment and routing
6. **Explore** – search and discovery features
7. **Lists** – Mastodon lists support
8. **MediaUI** – media handling components
9. **Models** – data models for Mastodon API
10. **Network** – networking layer and API client
11. **Notifications** – push and in-app notifications
12. **StatusKit** – post editor and status rendering
13. **Timeline** – timeline views and streaming logic

Each package has its own `Package.swift` file and is built with **Swift Package Manager**.

## Building the Project
1. Copy `IceCubesApp.xcconfig.template` to `IceCubesApp.xcconfig`.
2. Fill in the `DEVELOPMENT_TEAM` and `BUNDLE_ID_PREFIX` values.
3. Open `IceCubesApp.xcodeproj` in Xcode and build.

To build a package on the command line:
```bash
swift build
```

The following Swift packages are located in the `Packages` directory:
## Testing
Unit tests live in the `Tests` directory of each package. Run tests with:
```bash
cd Packages/<PackageName>
swift test
```
Many packages depend on Apple frameworks such as SwiftUI and will not build on a pure Linux environment.

1. **MediaUI** - UI components related to media.
2. **DesignSystem** - Design system components used across the app.
3. **Lists** - Package for list-related components.
4. **AppAccount** - Package for managing user accounts and authentication.
5. **Network** - Network-related functionality, such as API calls and data management.
6. **Models** - Contains data models used throughout the app.
7. **Explore** - Package for explore features, such as discovery of content.
8. **Env** - Environmental settings or configurations.
9. **Conversations** - Package for managing conversations or chat-related features.
10. **Account** - Handles user accounts and profile features.
11. **Timeline** - Package for timeline-related functionality, likely for displaying user posts or activities.
12. **Notifications** - Handles notifications functionality.
13. **StatusKit** - Contains status-related components, such as user status or activity status.
## Code Style
This repository uses [SwiftFormat](https://github.com/nicklockwood/SwiftFormat). The configuration is stored in `.swiftformat` and currently sets a two-space indentation. Format Swift files before committing if possible.

## How to Build the Project
## Contribution Tips
- Follow the MVVM pattern used throughout the packages.
- See `README.md` and `CLAUDE.md` for deeper explanations of features and architecture.
- CI scripts in `ci_scripts/` reveal environment variables required for automated builds.

If you're working on the project, you may be able to build it on Linux using the following command:
```bash
swift build
```
Happy coding!