Contributing

​

Welcome Contributors!

​

Getting Started

​

Prerequisites

• Android Studio (latest stable version recommended)
• JDK 8 or higher
• Android SDK with API level 26+ (Android 8.0 Oreo)
• Git for version control
• AnkiDroid installed on a test device or emulator

​

Development Setup

1. Clone the repository:
   git clone https://github.com/unalkalkan/AnkiDroid-Companion.git
   cd AnkiDroid-Companion
   
2. Open in Android Studio:
   • Launch Android Studio
   • Select “Open an Existing Project”
   • Navigate to the cloned repository
   • Wait for Gradle sync to complete
3. Configure AnkiDroid on your test device:
   • Install AnkiDroid from Google Play or F-Droid
   • Create at least one deck with some cards
   • Ensure AnkiDroid’s API is enabled (it’s enabled by default)
4. Build and run:
   ./gradlew assembleDebug
   
   Or use Android Studio’s “Run” button (Shift+F10)
5. Grant permissions: When you first launch the app, it will request the READ_WRITE_DATABASE permission. Grant this to allow API access.

​

Project Structure

AnkiDroid-Companion/
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/com/ankidroid/companion/
│   │   │   │   ├── MainActivity.kt              # Main UI activity
│   │   │   │   ├── AnkiDroidHelper.java         # API integration
│   │   │   │   ├── Notifications.kt             # Notification display
│   │   │   │   ├── NotificationReceiver.kt      # Button click handler
│   │   │   │   ├── PeriodicWorker.kt           # Background worker
│   │   │   │   ├── CardInfo.java               # Card data model
│   │   │   │   └── StoredState.java            # State data model
│   │   │   ├── res/
│   │   │   │   ├── layout/                     # UI layouts
│   │   │   │   └── values/                     # Strings, colors, etc.
│   │   │   └── AndroidManifest.xml
│   │   └── test/                               # Unit tests (future)
│   └── build.gradle.kts                        # App dependencies
├── gradle/
├── build.gradle.kts                            # Project config
└── README.md

​

Build Configuration

android {
    namespace = "com.ankidroid.companion"
    compileSdk = 34
    
    defaultConfig {
        applicationId = "com.ankidroid.companion"
        minSdk = 26    // Android 8.0+
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

​

Development Workflow

​

Making Changes

1. Create a feature branch:
   git checkout -b feature/your-feature-name
   
   Or for bug fixes:
   git checkout -b fix/issue-description
   
2. Make your changes:
   • Write clean, readable code
   • Follow existing code style
   • Add comments for complex logic
   • Test thoroughly on a real device
3. Test your changes:
   • Run the app on a physical device (emulator may have permission issues)
   • Test with different deck configurations
   • Verify notifications appear correctly
   • Test background worker behavior
   • Check that card reviews sync to AnkiDroid
4. Commit your changes:
   git add .
   git commit -m "Add feature: description of your changes"
   
   Write clear commit messages:
   • Use present tense (“Add feature” not “Added feature”)
   • Be concise but descriptive
   • Reference issue numbers if applicable
5. Push to your fork:
   git push origin feature/your-feature-name
   

​

Submitting a Pull Request

1. Push your branch to GitHub
2. Open a pull request on the main repository
3. Describe your changes:
   • What problem does this solve?
   • How did you test it?
   • Are there any breaking changes?
   • Screenshots/videos if UI changes
4. Wait for review:
   • Maintainers will review your PR
   • Address any requested changes
   • Be patient and responsive to feedback

​

Code Style Guidelines

• Kotlin: Follow Kotlin coding conventions
• Java: Follow Google Java Style Guide
• Indentation: 4 spaces (already configured in project)
• Naming:
  • Classes: PascalCase
  • Functions/variables: camelCase
  • Constants: UPPER_SNAKE_CASE

class NotificationHelper {
    private val channelId = "anki_channel"
    
    fun showCardNotification(card: CardInfo) {
        // Implementation
    }
    
    companion object {
        const val MAX_RETRY_COUNT = 3
    }
}

​

Known Limitations & Improvement Opportunities

​

1. Minimalistic Card Support

val questionText = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
    Html.fromHtml(card.q, Html.FROM_HTML_MODE_LEGACY).toString()
} else {
    @Suppress("DEPRECATION")
    Html.fromHtml(card.q).toString()
}

• Render HTML in a WebView within the notification
• Support image display in expanded notifications
• Add audio playback buttons for cards with sound
• Handle cloze deletions properly
• Support LaTeX/MathJax rendering

​

2. Skipping Cards

• Add a fifth “Skip” button to notifications
• Implement card burial (hide until next day)
• Add “Suspend” option to remove card from rotation

expandedView.setOnClickPendingIntent(R.id.button1, createIntent(context,"ACTION_BUTTON_1"))
expandedView.setOnClickPendingIntent(R.id.button2, createIntent(context,"ACTION_BUTTON_2"))
expandedView.setOnClickPendingIntent(R.id.button3, createIntent(context,"ACTION_BUTTON_3"))
expandedView.setOnClickPendingIntent(R.id.button4, createIntent(context,"ACTION_BUTTON_4"))
expandedView.setOnClickPendingIntent(R.id.buttonSkip, createIntent(context,"ACTION_SKIP")) // New

when (intent?.action) {
    "ACTION_BUTTON_1" -> respondCard(context, AnkiDroidHelper.EASE_1)
    "ACTION_BUTTON_2" -> respondCard(context, AnkiDroidHelper.EASE_2)
    "ACTION_BUTTON_3" -> respondCard(context, AnkiDroidHelper.EASE_3)
    "ACTION_BUTTON_4" -> respondCard(context, AnkiDroidHelper.EASE_4)
    "ACTION_SKIP" -> skipCard(context) // New handler
}

​

3. New Study Interval

val periodicWorkRequest = PeriodicWorkRequest.Builder(
    PeriodicWorker::class.java,
    8, TimeUnit.HOURS  // Hard-coded
).build()

• Add a settings screen
• Allow users to configure check interval (1-24 hours)
• Store preference in SharedPreferences
• Update worker when preference changes

// In SettingsActivity.kt (new file)
class SettingsActivity : AppCompatActivity() {
    private fun saveInterval(hours: Int) {
        val prefs = getSharedPreferences("app_settings", Context.MODE_PRIVATE)
        prefs.edit().putInt("check_interval_hours", hours).apply()
        
        // Reschedule worker with new interval
        schedulePeriodicWorker(hours)
    }
}

// In MainActivity.kt
private fun getCheckInterval(): Long {
    val prefs = getSharedPreferences("app_settings", Context.MODE_PRIVATE)
    return prefs.getInt("check_interval_hours", 8).toLong()
}

​

4. Embedded Strings

// MainActivity.kt:34
val name = "AnkiNotificationChannel"  // Should be in strings.xml

// Notifications.kt:43
collapsedView.setTextViewText(R.id.textViewCollapsedTitle, "Anki • $deckName")

// Notifications.kt:64
collapsedView.setTextViewText(R.id.textViewCollapsedHeader, 
    "Congrats! You've finished the deck!")  // Hard-coded

<resources>
    <string name="notification_channel_name">AnkiNotificationChannel</string>
    <string name="notification_title_format">Anki • %1$s</string>
    <string name="deck_finished_header">Congrats! You\'ve finished the deck!</string>
    <string name="deck_finished_content">New notifications will arrive when it\'s time to study!</string>
</resources>

val name = getString(R.string.notification_channel_name)
collapsedView.setTextViewText(
    R.id.textViewCollapsedHeader, 
    getString(R.string.deck_finished_header)
)

​

5. Future Features

• Home screen widget: Quick access to study without opening notification shade
• Lock screen widget: Study while phone is locked
• Statistics view: Track daily/weekly review counts
• Multiple deck support: Rotate between multiple decks
• Custom notification layouts: User-configurable button labels and colors

​

Reporting Issues

​

Before Opening an Issue

1. Search existing issues to avoid duplicates
2. Update AnkiDroid to the latest version
3. Check if permissions are granted in Android settings
4. Test on a physical device (emulators may behave differently)

​

Opening a Bug Report

• Device information: Make, model, Android version
• AnkiDroid version: Check in AnkiDroid’s About screen
• App version: Check in app settings or build.gradle.kts
• Steps to reproduce: Detailed steps to trigger the bug
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Logs: Use adb logcat to capture relevant logs
• Screenshots/videos: If applicable

**Device:** Pixel 6, Android 14
**AnkiDroid:** v2.17.6
**Companion:** v1.0 (commit abc123)

**Steps to reproduce:**
1. Open app and select "Japanese" deck
2. Click Refresh button
3. Notification appears
4. Click "Good" button

**Expected:** Next card should appear
**Actual:** Notification disappears completely

**Logs:**

​

Opening a Feature Request

• What feature you’d like to see
• Why it would be useful: Use cases, user stories
• How it might work: Proposed UI/UX or implementation
• Related features: Similar apps or AnkiDroid features

​

Testing

​

Manual Testing Checklist

• App launches successfully
• Permission request appears on first launch
• Deck list populates correctly
• Clicking “Refresh” shows notification
• Notification displays question and answer
• All four buttons work (Again, Hard, Good, Easy)
• Next card appears after answering
• Completion notification shows when deck is finished
• Periodic worker runs after 8 hours (test by changing interval)
• App works after device restart
• State persists across app restarts
• Works with renamed decks
• Works with multiple decks (switching between them)

​

Testing with ADB

adb logcat | grep -E "(Notifications|BackgroundService|AnkiDroidHelper)"

adb shell am broadcast -a android.intent.action.BOOT_COMPLETED

adb shell pm clear com.ankidroid.companion

adb shell run-as com.ankidroid.companion cat /data/data/com.ankidroid.companion/shared_prefs/com.ichi2.anki.api.state.xml

​

License

​

Getting Help

1. Check existing documentation in this wiki
2. Read the source code: It’s well-commented
3. Open a discussion: For questions about implementation
4. Ask in issues: Tag with “question” label

​

Recognition

• Listed in the GitHub contributors page
• Mentioned in release notes for significant contributions
• Thanked in the project README