Airframe Scala Development

Development guidelines for the wvlet/airframe project - Essential Building Blocks for Scala. This skill provides coding standards, testing practices, and workflow patterns for contributing to the Airframe ecosystem.

Tech Stack

**Primary Languages**: Scala, Scala.js, Scala Native

**Scala Versions**: Prioritize Scala 2.13 syntax for broad compatibility. Scala 2.12 compatible syntax is also acceptable

**Scala 3**: Use Scala 3 specific syntax **only** within `src/{main,test}/scala3` directories

**Build Tool**: sbt (Scala Build Tool)

**Testing Framework**: AirSpec

Project Structure and Modules

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

**Platform-specific code**:

- JVM: `.jvm/src/main/scala`, `.jvm/src/test/scala`

- JS: `.js/src/main/scala`, `.js/src/test/scala`

- Native: `.native/src/main/scala`, `.native/src/test/scala`

- Shared code (common to all platforms) resides in `src/main/scala` and `src/test/scala`

**Core module** `airframe-core` 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

1. **Formatting**: Before committing changes, run `./sbt scalafmtAll` to properly format the Scala code according to project guidelines. For targeted formatting of specific modules, use `./sbt "(moduleNameJVM)/scalafmtAll"` (replace `moduleNameJVM` with your target module)

2. **Case Classes**: Configuration case classes should have `withXXX(...)` methods for all fields and `noXXX(...)` methods for all optional fields

3. **String Interpolation**: Always enclose expressions with brackets `${...}` for consistency

4. **Error Handling**: Returning `Try[A]` is generally discouraged as it forces a monadic style on the caller. Consider using plain exceptions for unrecoverable errors, or domain-specific error types

Dependencies

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

**When adding a dependency**:

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

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

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

Testing

Running Tests

Use `./sbt` command to open sbt shell

Compile source and test code:

- JVM: `./sbt projectJVM/Test/compile`

- JS: `./sbt projectJS/Test/compile`

- Native: `./sbt projectNative/Test/compile`

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

**Run specific test class**: `./sbt '(moduleName)(JVM|JS|Native)/testOnly *TestClassName'`

- Example for JVM test in `airframe-log` module: `./sbt 'logJVM/testOnly *MyLogTest'`

- Example for JS test in `airframe-codec` module: `./sbt 'codecJS/testOnly fully.qualified.TestClassName'`

Writing Tests

Use **AirSpec** testing framework. Key assertion syntaxes include `shouldBe`, `shouldNotBe`, `shouldMatch`

Test names should be concise and descriptive, written in plain English

**Avoid using mock** as it increases maintenance cost

Ensure tests cover new functionality and bug fixes. Aim for good test coverage

When a test fails, carefully analyze the stack trace and assertion failures from the sbt output. The output will indicate the exact line of failure

Git Workflow

Branching

Use `gh` command for GitHub operations

For creating a new branch use: `git switch -c feature/$(date +"%Y%m%d_%H%M%S")-your-feature-description`

The branch naming convention `feature/$(date +"%Y%m%d_%H%M%S")` can be adapted for other types of changes:

- `fix/$(date +"%Y%m%d_%H%M%S")-brief-description`

- `doc/$(date +"%Y%m%d_%H%M%S")-brief-description`

- `internal/$(date +"%Y%m%d_%H%M%S")-brief-description`

Commit Messages

Format: `feature: xxx` (for new features), `fix` (bug fixes), `internal` (non-user facing changes), or `doc` based on the code change contents

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

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

Poor: `feature: Add XXX class`

Pull Requests

Use `gh pr create` for creating pull requests. Provide a clear title and a detailed body, linking to any relevant issues

Follow `.github/pull_request_template.md` format for PR descriptions

**Prefer squashing commits** via auto-merge with `gh pr merge --squash --auto` command when merging PRs to maintain a linear and clean history on the main branch

Key Constraints

Keep `airframe-core` dependency-free unless absolutely necessary

Ensure cross-platform compatibility (JVM/JS/Native) when working on shared modules

Run `scalafmtAll` before committing

Write tests for all new functionality and bug fixes

Use Scala 2.13 syntax by default; Scala 3 syntax only in `scala3` directories

Airframe Scala Development

Airframe Scala Development

Tech Stack

Project Structure and Modules

Coding Style

Dependencies

Testing

Running Tests

Writing Tests

Git Workflow

Branching

Commit Messages

Pull Requests

Key Constraints

Reviews (0)