Scala Multi-Platform Development with Airframe

Guidelines for developing Scala projects with multi-platform (JVM/JS/Native) cross-building, sbt multi-module structure, AirSpec testing, and airframe coding conventions.

Tech Stack Context

Project Structure

This is a multi-module sbt project where most modules are cross-built for JVM, JS, and Native platforms.

Platform-Specific Code Locations

Core Module Principles

The `airframe-core` module is designed for minimal dependencies. Avoid adding new library dependencies to `airframe-core` unless absolutely necessary. For other modules, carefully consider the impact of adding new dependencies.

Coding Style

Formatting

Before committing changes, run:

```bash

./sbt scalafmtAll

```

This ensures consistent code style across the codebase according to project guidelines.

For targeted formatting of specific modules:

```bash

./sbt "(moduleNameJVM)/scalafmtAll"

```

Replace `moduleNameJVM` with your target module name.

Style Conventions

Dependency Management

Checking Dependencies

Check `libraryDependencies` in `build.sbt` for each module to understand its current dependencies.

Adding Dependencies

When adding a dependency:

1. Ensure it's available for all relevant platforms (JVM, JS, Native) if the module is cross-built

2. Prefer libraries already used in other modules if similar functionality is needed

3. For `airframe-core`, new dependencies are highly discouraged

Testing

Compiling Tests

Open sbt shell:

```bash

./sbt

```

Compile source and test code:

Replace `project` with the actual module name (e.g., `logJVM/Test/compile`).

Running Specific Tests

```bash

./sbt '(moduleName)(JVM|JS|Native)/testOnly *TestClassName'

```

Examples:

Testing Best Practices

Git Workflow

Branch Naming

Use timestamped feature branches:

```bash

git switch -c feature/$(date +"%Y%m%d_%H%M%S")-your-feature-description

```

Adapt for other change types:

Commit Message Format

Format: `<type>: <description>`

Focus on the **why** of the change, not the **what** or **how**.

Good: `feature: Add XXX to improve user experience`

Bad: `feature: Add XXX class`

Pull Requests

Use `gh` command for GitHub operations:

```bash

gh pr create

```

Provide a clear title and detailed body, linking to any relevant issues. Follow `.github/pull_request_template.md` format for PR descriptions.

Merging PRs

Prefer squashing commits via auto-merge to maintain a linear and clean history on the main branch:

```bash

gh pr merge --squash --auto

```

Key Reminders