# Coding Guidelines for SubSonicSter

## Version Management

When making code changes that require a version bump:

1. **Always update version numbers** in `app/build.gradle.kts`:
   - Update `versionCode` (increment by 1)
   - Update `versionName` (following semantic versioning)

2. **Always update `CHANGELOG.md`**:
   - Add a new entry at the top for the new version
   - Follow the existing format and structure
   - **IMPORTANT: All entries in CHANGELOG.md must be written in English**

3. **If no version is specified** by the user:
   - **Ask the user** what version number should be used before making changes
   - Do not assume or guess version numbers

## CHANGELOG.md Language

- **All entries in CHANGELOG.md must be written in English**
- This applies to:
  - Version headers
  - Feature descriptions
  - Technical details
  - All other content in the changelog

## Example Workflow

When implementing features or fixes:
1. Ask for version number if not provided
2. Implement the changes
3. Update `app/build.gradle.kts` with new version
4. Update `CHANGELOG.md` with new entry (in English)
5. **Synchronize `app/src/main/assets/LICENSES_THIRD_PARTY.md`** with actual dependencies (see "License File Synchronization" section)

## Zero Warnings Policy

**⚠️ This project treats ALL compiler and lint warnings as errors. The build will fail if any warnings are present.**

- Kotlin compiler: `allWarningsAsErrors = true`
- Java compiler: `-Werror` flag enabled
- Android Lint: `warningsAsErrors = true`

This applies to all code changes. When writing or modifying code:
- **Never introduce new warnings** – fix the root cause instead
- **Never suppress warnings** with `@Suppress` or `//noinspection` unless absolutely unavoidable and clearly justified
- **Never disable lint checks** in `build.gradle.kts` unless discussed with the user
- If a warning appears after a change, **fix it before completing the task**

See `README.md` (section "Code Quality Standards") and `gradle.properties` for full documentation.

## Dependency Update Check

**When to check for updates:**
- After completing code changes that require a version bump (before updating `CHANGELOG.md`)
- When the user explicitly requests dependency updates
- **Always ask the user** if they want to check for dependency updates before proceeding

**Update Algorithm:**

1. **Check for available updates:**
   - Run `./gradlew dependencyUpdates` (or `.\gradlew.bat dependencyUpdates` on Windows)
   - Review the generated report in `build/dependencyUpdates/report.txt`
   - Identify stable (non-alpha/beta/RC) updates

2. **Apply updates one by one:**
   - Update **only one dependency at a time** in `gradle/libs.versions.toml`
   - Run `./gradlew build --no-configuration-cache` to test
   - **If build succeeds:** Keep the update and proceed to the next dependency
   - **If build fails:** Revert the change immediately and document the incompatibility, then continue with the next dependency

3. **Document successful updates:**
   - Add a "Changed" section to `CHANGELOG.md` (if not already present)
   - List all successfully updated dependencies with their version changes
   - Include technical details about the updates
   - **CRITICAL: Update `app/src/main/assets/LICENSES_THIRD_PARTY.md`** with all version changes
     - This file is displayed in the OpenSourceLicenses screen (`LicensesScreen.kt`)
     - Update version numbers for all affected libraries
     - Update the "Last Updated" date at the bottom of the file
     - Ensure all library versions match those in `gradle/libs.versions.toml`

4. **Important rules:**
   - **Only update stable versions** - skip alpha, beta, and RC releases unless explicitly requested
   - **Never update multiple dependencies simultaneously** - always test one at a time
   - **Always revert failed updates** - do not leave the project in a broken state
   - **Document incompatibilities** - note why certain updates couldn't be applied (e.g., requires newer AGP version)

**Example workflow:**
1. Complete code changes
2. Ask user: "Should I check for dependency updates and apply them?"
3. If yes: Run update check, apply updates one by one, document in CHANGELOG.md
4. If no: Proceed with version bump and CHANGELOG.md update as normal

## License File Synchronization

**When to perform synchronization:**
- **Always** when updating version numbers (as part of the version bump process)
- **Always** after dependency updates (library version changes)
- **Always** before finalizing a release

**Synchronization Process:**

1. **Compare actual dependencies with license file:**
   - Read all `implementation()` dependencies from `app/build.gradle.kts`
   - Compare with libraries listed in `app/src/main/assets/LICENSES_THIRD_PARTY.md`
   - Identify:
     - Libraries in `build.gradle.kts` but missing in license file
     - Libraries in license file but not in `build.gradle.kts`
     - Version mismatches between `gradle/libs.versions.toml` and license file

2. **Update license file:**
   - **Add missing libraries** that are actually used in `build.gradle.kts`
   - **Remove libraries** that are no longer in `build.gradle.kts` (unless they are transitive dependencies that need to be documented)
   - **Update version numbers** to match `gradle/libs.versions.toml`
   - For Compose libraries managed by BOM, use format: `(via Compose BOM 2026.02.00)`
   - **Do NOT include transitive-only dependencies** unless they are significant and need explicit attribution

3. **Verify accuracy:**
   - Ensure every `implementation()` dependency in `app/build.gradle.kts` is listed in the license file
   - Ensure all version numbers match `gradle/libs.versions.toml`
   - Update "Last Updated" date at the bottom of the license file
   - Update "SubSonicSter Version" to match current version

4. **Important rules:**
   - **Only list directly declared dependencies** - transitive dependencies are covered by their parent library's license
   - **Exception**: If a transitive dependency has a different license or requires explicit attribution, include it
   - **Keep version numbers accurate** - the license file is displayed to users in the OpenSourceLicenses screen
   - **Use correct version format** - BOM-managed libraries should indicate they're managed by BOM

**Example workflow:**
1. After updating version numbers in `app/build.gradle.kts`
2. Read `app/build.gradle.kts` dependencies section
3. Read `app/src/main/assets/LICENSES_THIRD_PARTY.md`
4. Compare and identify differences
5. Update license file to match actual dependencies
6. Verify all versions match `gradle/libs.versions.toml`
