Contributing Guidelines

Thank you for your interest in contributing to Kafka! This guide will help you get started with contributing to the project.

Getting Started

Before you begin:

Set up your development environment - Follow the setup guide
Understand the architecture - Review the architecture overview
Build the project - Ensure you can build successfully
Run the tests - Familiarize yourself with the testing approach

Ways to Contribute

There are many ways to contribute to Kafka:

Report Bugs

Found a bug? Report it on GitHub Issues with details and reproduction steps

Suggest Features

Have an idea? Open a feature request to discuss it with the community

Improve Documentation

Help others by improving or adding documentation

Write Code

Fix bugs, add features, or improve existing functionality

Write Tests

Increase test coverage for better code quality

Review PRs

Help review pull requests from other contributors

Code Contribution Process

Find or Create an Issue

Before writing code:

Check if an issue exists for what you want to work on
If not, create a new issue describing the bug or feature
Comment on the issue to let others know you’re working on it
Wait for feedback from maintainers if it’s a significant change

Fork and Clone

Fork the Kafka repository on GitHub
Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/Kafka.git
cd Kafka

Add the upstream repository:

git remote add upstream https://github.com/vipulyaara/Kafka.git

Clone Sarahang dependency:

cd ..
git clone https://github.com/vipulyaara/Sarahang.git

Create a Branch

Create a new branch for your work:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Use descriptive branch names:

feature/add-bookmark-sync
fix/audio-playback-crash
docs/update-setup-guide
test/add-search-tests

Make Your Changes

Write your code following the project conventions:

Follow the existing code style
Use meaningful variable and function names
Add comments for complex logic
Keep commits focused and atomic
Write/update tests for your changes

Test Your Changes

Before committing, ensure:

# Format code
./gradlew spotlessApply

# Run lint
./gradlew lintDebug

# Run tests
./gradlew test

# Build the app
./gradlew assembleDebug

# Test on a device/emulator
./gradlew installDebug

Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add bookmark sync feature

- Implement bookmark synchronization with Archive.org
- Add sync settings to user preferences
- Update UI to show sync status

Fixes #123"

Reference the issue number in your commit message using Fixes #123 or Closes #123.

Push and Create Pull Request

Push your branch to your fork:

git push origin feature/your-feature-name

Go to GitHub and create a Pull Request
Fill out the PR template with:
- Description of changes
- Issue number (Fixes #123)
- Screenshots/videos (for UI changes)
- Testing done

Address Review Feedback

Be responsive to review comments
Make requested changes promptly
Push additional commits to your branch
Re-request review when ready

# Make changes based on feedback
git add .
git commit -m "Address review feedback"
git push origin feature/your-feature-name

Coding Standards

Kotlin Style Guide

Kafka follows the official Kotlin coding conventions.

Naming Conventions

// Classes and objects: PascalCase
class BookRepository
object NetworkModule

// Functions and properties: camelCase
fun fetchBooks(): List<Book>
val currentUser: User

// Constants: UPPER_SNAKE_CASE
const val MAX_RETRY_ATTEMPTS = 3

// Compose functions: PascalCase
@Composable
fun BookListScreen()

File Organization

// 1. Package declaration
package com.kafka.ui.books

// 2. Imports (organized alphabetically)
import androidx.compose.runtime.*
import com.kafka.data.model.Book

// 3. Top-level declarations
private const val TAG = "BookScreen"

// 4. Class/object declarations
class BookViewModel(...) { ... }

Composable Functions

@Composable
fun BookCard(
    book: Book,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,  // Modifier always last with default
) {
    Card(
        modifier = modifier.clickable(onClick = onClick)
    ) {
        // Composable content
    }
}

Coroutines and Flow

class BookRepository {
    // Use Flow for streams
    fun observeBooks(): Flow<List<Book>> = flow {
        // Implementation
    }
    
    // Use suspend for single operations
    suspend fun fetchBook(id: String): Result<Book> {
        // Implementation
    }
}

Code Formatting

Kafka uses Spotless with ktlint for automatic code formatting:

# Apply formatting before committing
./gradlew spotlessApply

# Check if code is properly formatted
./gradlew spotlessCheck

Formatting rules:

4 spaces for indentation (no tabs)
Trailing whitespace removed
Files end with newline
Maximum line length: 120 characters (recommended)

Architecture Guidelines

Kafka follows MVVM architecture with clean architecture principles:

ui/ (Presentation Layer)
├── screens/
│   ├── BookScreen.kt          # Composable UI
│   └── BookViewModel.kt       # UI state and logic
│
domain/ (Domain Layer)
├── usecases/
│   └── GetBookUseCase.kt      # Business logic
│
data/ (Data Layer)
├── repository/
│   └── BookRepository.kt      # Data operations
├── database/
│   └── BookDao.kt            # Local storage
└── models/
    └── Book.kt               # Data models

Refer to the Architecture Overview for detailed information about the project structure.

Dependency Injection

Kafka uses kotlin-inject for dependency injection:

@Inject
class BookRepository(
    private val bookDao: BookDao,
    private val api: BookApi,
) {
    // Implementation
}

@Component
abstract class AppComponent {
    abstract val bookRepository: BookRepository
}

Pull Request Guidelines

PR Description Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issue
Fixes #(issue number)

## Changes Made
- Change 1
- Change 2
- Change 3

## Screenshots/Videos
(If applicable, add screenshots or videos)

## Testing
- [ ] Unit tests added/updated
- [ ] UI tests added/updated
- [ ] Manual testing performed
- [ ] Tested on physical device
- [ ] Tested on emulator

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-reviewed the code
- [ ] Commented complex code sections
- [ ] Updated documentation
- [ ] No new warnings introduced
- [ ] All tests pass
- [ ] Spotless formatting applied

PR Best Practices

Keep PRs Focused

One PR should address one issue or feature
Avoid mixing unrelated changes
Split large changes into multiple PRs

Write Clear Descriptions

Explain what and why, not just how
Reference related issues
Include screenshots for UI changes
Describe testing performed

Keep It Small

Aim for < 400 lines changed when possible
Easier to review and less likely to have bugs
Faster to merge

Update Documentation

Update README if needed
Add/update code comments
Update API documentation

Reporting Issues

Bug Reports

When reporting bugs, include:

## Bug Description
Clear description of the bug

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- Kafka Version: 0.48.0
- Android Version: 14
- Device: Pixel 6
- Build Type: Debug/Release

## Logs/Screenshots
(If applicable)

Feature Requests

When requesting features, include:

## Feature Description
Clear description of the feature

## Use Case
Why is this feature needed?

## Proposed Solution
How should it work?

## Alternatives Considered
Other approaches you've thought about

## Additional Context
Screenshots, mockups, examples from other apps

Code Review Process

For Contributors

Be patient - maintainers review PRs in their spare time
Respond to feedback constructively
Don’t take criticism personally
Ask questions if feedback is unclear

For Reviewers

Be respectful and constructive
Explain the reasoning behind suggestions
Approve PRs that improve the codebase
Request changes for issues that need fixing

Community Guidelines

Be respectful - Treat everyone with respect and kindness
Be collaborative - Work together to improve the project
Be patient - Understand that contributors have different skill levels
Be constructive - Provide helpful feedback and suggestions
Give credit - Acknowledge the work of others

Recognition

All contributors will be:

Listed in the GitHub contributors page
Mentioned in release notes (for significant contributions)
Part of the Kafka community

Getting Help

If you need help:

Check the documentation - Most questions are answered here
Search existing issues - Your question might already be answered
Ask in discussions - Use GitHub Discussions for questions
Create an issue - If you found a bug or have a specific question

License

By contributing to Kafka, you agree that your contributions will be licensed under the same license as the project.

Resources

GitHub Repository

View the source code

Issue Tracker

Report bugs and request features

Architecture Guide

Understand the codebase structure

Kotlin Docs

Learn Kotlin programming

Thank You!

Your contributions make Kafka better for everyone. Whether it’s code, documentation, bug reports, or feature suggestions - every contribution matters. Happy coding! 🚀

Architecture

Core Components

Development

Contributing Guidelines

Getting Started

Ways to Contribute

Report Bugs

Suggest Features

Improve Documentation

Write Code

Write Tests

Review PRs

Code Contribution Process

Coding Standards

Kotlin Style Guide

Code Formatting

Architecture Guidelines

Dependency Injection

Pull Request Guidelines

PR Description Template

PR Best Practices

Reporting Issues

Bug Reports

Feature Requests

Code Review Process

For Contributors

For Reviewers

Community Guidelines

Recognition

Getting Help

License

Resources

GitHub Repository

Issue Tracker

Architecture Guide

Kotlin Docs

Thank You!

Build docs developers (and LLMs) love

Architecture

Core Components

Development

​Getting Started

​Ways to Contribute

Report Bugs

Suggest Features

Improve Documentation

Write Code

Write Tests

Review PRs

​Code Contribution Process

​Coding Standards

​Kotlin Style Guide

​Code Formatting

​Architecture Guidelines

​Dependency Injection

​Pull Request Guidelines

​PR Description Template

​PR Best Practices

​Reporting Issues

​Bug Reports

​Feature Requests

​Code Review Process

​For Contributors

​For Reviewers

​Community Guidelines

​Recognition

​Getting Help

​License

​Resources

GitHub Repository

Issue Tracker

Architecture Guide

Kotlin Docs

​Thank You!

Build docs developers (and LLMs) love

Getting Started

Ways to Contribute

Code Contribution Process

Coding Standards

Kotlin Style Guide

Code Formatting

Architecture Guidelines

Dependency Injection

Pull Request Guidelines

PR Description Template

PR Best Practices

Reporting Issues

Bug Reports

Feature Requests

Code Review Process

For Contributors

For Reviewers

Community Guidelines

Recognition

Getting Help

License

Resources

Thank You!