Contributing Guide - Aradia Audiobooks

Welcome Contributors!

Thank you for your interest in contributing to Aradia Audiobooks! We welcome contributions from developers of all skill levels. Whether you’re fixing bugs, adding features, or improving documentation, your help is appreciated.

Getting Started

Fork the Repository

Fork the repository on GitHub:

# Navigate to https://github.com/sagarchaulagai/aradia
# Click the "Fork" button

Clone Your Fork

Clone your forked repository:

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

Add Upstream Remote

Add the original repository as upstream:

git remote add upstream https://github.com/sagarchaulagai/aradia.git

Set Up Development Environment

Follow the Building from Source guide to set up your development environment.

Development Workflow

Create a Feature Branch

Always create a new branch for your work:

# Update your main branch
git checkout main
git pull upstream main

# Create a new feature branch
git checkout -b feature/your-feature-name

Use descriptive branch names:

feature/add-podcast-support
fix/audio-playback-crash
docs/update-installation-guide

Make Your Changes

Code Changes
Documentation

Follow Code Style

Aradia follows standard Dart/Flutter conventions:

# Format your code
flutter format .

# Analyze code
flutter analyze

Write Tests

Add tests for new features:

test/widget_test.dart

import 'package:flutter_test/flutter_test.dart';
import 'package:aradia/main.dart';

void main() {
  testWidgets('Counter increments smoke test', (WidgetTester tester) async {
    await tester.pumpWidget(const MyApp());
    // Add your test logic
  });
}

Test Your Changes

Run the app and verify your changes:

flutter run

Update Documentation

If your changes affect user-facing features, update the documentation.

Add Code Comments

Add comments for complex logic:

/// Fetches audiobooks from Archive.org API
/// 
/// [page] - The page number for pagination
/// [rows] - Number of results per page
/// Returns Either an error message or list of audiobooks
Future<Either<String, List<Audiobook>>> getLatestAudiobook(
  int page, 
  int rows
) async {
  // Implementation
}

Update README

If adding major features, update the README.md.

Code Standards

BLoC Pattern Guidelines

When creating new BLoCs, follow the existing pattern:

class ExampleBloc extends Bloc<ExampleEvent, ExampleState> {
  ExampleBloc() : super(ExampleInitial()) {
    on<EventName>(_onEventName);
  }

  Future<void> _onEventName(
    EventName event,
    Emitter<ExampleState> emit,
  ) async {
    emit(ExampleLoading());
    
    try {
      // Business logic
      final result = await fetchData();
      emit(ExampleSuccess(result));
    } catch (e) {
      emit(ExampleFailure(e.toString()));
    }
  }

  @override
  Future<void> close() {
    // Clean up resources
    return super.close();
  }
}

Provider Guidelines

For global state, use ChangeNotifier with Provider:

class ExampleNotifier extends ChangeNotifier {
  DataType _data = initialValue;
  DataType get data => _data;

  void updateData(DataType newData) {
    _data = newData;
    notifyListeners();
  }

  @override
  void dispose() {
    // Clean up resources
    super.dispose();
  }
}

File Organization

lib/
├── screens/
│   └── feature_name/
│       ├── feature_screen.dart       # Main screen widget
│       ├── bloc/                     # BLoC files (if needed)
│       │   ├── feature_bloc.dart
│       │   ├── feature_event.dart
│       │   └── feature_state.dart
│       └── widgets/                  # Feature-specific widgets
│           └── custom_widget.dart
├── resources/
│   ├── models/                       # Data models
│   ├── services/                     # Business logic
│   └── designs/                      # Themes and styles
└── widgets/                          # Shared widgets

Commit Guidelines

Commit Message Format

Use clear, descriptive commit messages:

type(scope): brief description

Detailed explanation if needed.

Fixes #issue_number

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(player): add sleep timer functionality

Implemented a sleep timer that allows users to set a 
timer for automatic playback stop.

Fixes #123

fix(download): resolve crash on storage permission denial

Added proper error handling when storage permission is denied.

Making Commits

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "feat(search): implement advanced search filters"

# Push to your fork
git push origin feature/your-feature-name

Pull Request Process

Sync with Upstream

Before creating a PR, sync with the latest upstream:

git checkout main
git pull upstream main
git checkout feature/your-feature-name
git rebase main

Create Pull Request

Go to your fork on GitHub
Click “New Pull Request”
Select your feature branch
Fill in the PR template

PR Description Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

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

## Screenshots (if applicable)

## Testing
- [ ] Tested on Android
- [ ] Tested on iOS
- [ ] Added/updated tests

## Related Issues
Fixes #issue_number

Address Review Comments

If reviewers request changes:

# Make changes
git add .
git commit -m "address review comments"
git push origin feature/your-feature-name

Areas for Contribution

Bug Fixes

Check the Issues page for bugs to fix

New Features

Implement features from the roadmap or propose new ones

Documentation

Improve documentation, add examples, or fix typos

Testing

Add unit tests, widget tests, or integration tests

Performance

Optimize code, reduce memory usage, or improve loading times

UI/UX

Enhance the user interface and user experience

Issue Reporting

Before Creating an Issue

Bug Report Template

## Bug Description
A clear and concise description of the bug.

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

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Screenshots
If applicable, add screenshots.

## Environment
- Device: [e.g. Pixel 6]
- OS: [e.g. Android 13]
- App Version: [e.g. 3.0.0]

## Additional Context
Any other relevant information.

Feature Request Template

## Feature Description
A clear and concise description of the feature.

## Use Case
Why is this feature needed? What problem does it solve?

## Proposed Solution
How you envision this feature working.

## Alternatives Considered
Other approaches you've thought about.

## Additional Context
Mockups, examples, or references.

Community

Discord

Join our Discord community for discussions

GitHub Discussions

Participate in GitHub Discussions for Q&A

Code of Conduct

Our Standards

Be respectful and inclusive
Welcome newcomers and help them get started
Accept constructive criticism gracefully
Focus on what’s best for the community
Show empathy towards others

Unacceptable Behavior

Harassment or discriminatory language
Trolling or insulting comments
Publishing others’ private information
Any conduct that could reasonably be considered inappropriate

Recognition

Contributors are recognized in:

GitHub contributors page
Release notes for significant contributions
Special mentions in the README for major features

Support the Project

If you find this project useful, consider:

Starring the repository on GitHub
Sharing the app with others
Supporting via Ko-fi
Contributing code or documentation

Questions?

If you have questions about contributing:

Check the documentation
Ask in Discord
Create a GitHub Discussion
Reach out to maintainers

Remember: Every contribution, no matter how small, is valuable and appreciated!

Next Steps

Architecture

Understand the codebase architecture

Building from Source

Set up your development environment

State Management

Learn about BLoC and Provider patterns

Get Started

Features

User Guide

Development

​Welcome Contributors!

​Getting Started

​Development Workflow

​Create a Feature Branch

​Make Your Changes

​Code Standards

​BLoC Pattern Guidelines

​Provider Guidelines

​File Organization

​Commit Guidelines

​Commit Message Format

​Making Commits

​Pull Request Process

​Areas for Contribution

Bug Fixes

New Features

Documentation

Testing

Performance

UI/UX

​Issue Reporting

​Before Creating an Issue

​Bug Report Template

​Feature Request Template

​Community

Discord

GitHub Discussions

​Code of Conduct

​Our Standards

​Unacceptable Behavior

​Recognition

​Support the Project

​Questions?

​Next Steps

Architecture

Building from Source

State Management

Build docs developers (and LLMs) love

Welcome Contributors!

Getting Started

Development Workflow

Create a Feature Branch

Make Your Changes

Code Standards

BLoC Pattern Guidelines

Provider Guidelines

File Organization

Commit Guidelines

Commit Message Format

Making Commits

Pull Request Process

Areas for Contribution

Issue Reporting

Before Creating an Issue

Bug Report Template

Feature Request Template

Community

Code of Conduct

Our Standards

Unacceptable Behavior

Recognition

Support the Project

Questions?

Next Steps