Contributing Guidelines

​

Code of Conduct

​

Our Pledge

• Be respectful and inclusive
• Use welcoming and inclusive language
• Be respectful of differing viewpoints and experiences
• Accept constructive criticism gracefully
• Focus on what’s best for the community
• Show empathy towards other community members

​

Unacceptable Behavior

• The use of sexualized language or imagery
• Trolling, insulting/derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others’ private information without explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

​

Getting Started

​

Prerequisites

• Android Studio Hedgehog or later
• JDK 17 or later
• Android SDK 26 or later
• Git
• Basic knowledge of Kotlin and Android development
• Understanding of Jetpack Compose (preferred)
• Familiarity with MVVM architecture pattern

​

Fork and Clone

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

git remote add upstream https://github.com/jed1boy/Musika.git

​

Development Setup

​

Environment Setup

cp local.properties.template local.properties

sdk.dir=/path/to/your/Android/sdk

​

Firebase Setup (Optional)

cp app/google-services.json.template app/google-services.json

​

Build the Project

./gradlew assembleDebug

​

Handling Sensitive Information

​

Files That Should Never Be Committed

​

Best Practices

• API Keys: Never hardcode API keys in the source code
• Credentials: Never include usernames, passwords, or tokens in commits
• Personal Information: Remove any personal information before committing
• Before Committing: Always review your changes to ensure no sensitive information is included
• If Accidentally Committed: If you accidentally commit sensitive information, contact a project maintainer immediately

​

Types of Contributions

• Bug Fixes: Fix existing issues and improve stability
• New Features: Add new functionality and capabilities
• Documentation: Improve documentation and guides
• UI/UX Improvements: Enhance user interface and experience
• Performance: Optimize app performance and memory usage
• Testing: Add or improve tests and test coverage
• Translations: Add new language support and improve existing translations
• Code Quality: Refactor code, improve architecture, and fix code smells
• Security: Identify and fix security vulnerabilities

​

Before You Start

1. Check existing issues to see if your idea is already being discussed
2. Create an issue for significant changes to discuss the approach
3. Fork the repository and create a feature branch
4. Follow the coding standards outlined below

​

Pull Request Process

​

Create a Branch

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

​

Make Your Changes

• Write clean, readable code
• Follow the existing code style
• Add comments for complex logic
• Update documentation if needed
• Add tests for new features

​

Test Your Changes

./gradlew test

​

Commit Your Changes

git add .
git commit -m "feat: add dark mode toggle to settings

- Add dark mode preference in settings
- Update theme switching logic
- Add corresponding UI tests

Fixes #123"

​

Commit Message Prefixes

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• style: for formatting changes
• refactor: for code refactoring
• test: for adding tests
• chore: for maintenance tasks

​

Push and Create PR

git push origin feature/your-feature-name

• Clear title and description
• Reference to related issues
• Screenshots for UI changes
• Testing instructions

​

Issue Guidelines

​

Bug Reports

1. Clear title describing the issue
2. Steps to reproduce the bug
3. Expected behavior vs actual behavior
4. Screenshots or videos if applicable
5. Device information (Android version, device model)
6. App version and build type
7. Logs if available
8. Environment details (build variant, configuration)

​

Feature Requests

1. Clear title describing the feature
2. Detailed description of the feature
3. Use case and why it would be useful
4. Mockups or examples if applicable
5. Alternative solutions you’ve considered
6. Impact assessment (user experience, performance, etc.)

​

Coding Standards

​

Kotlin Style

• Follow Kotlin Coding Conventions
• Use meaningful variable and function names
• Prefer val over var when possible
• Use data classes for simple data holders
• Use sealed classes for state management

​

Android Best Practices

• Follow Android Code Style Guidelines
• Use Jetpack Compose for UI
• Implement MVVM architecture
• Use Repository pattern for data access
• Handle lifecycle properly

​

Code Organization

app/src/main/kotlin/com/musika/app/
├── ui/                    # UI components and screens
│   ├── components/        # Reusable UI components
│   ├── screens/          # Screen-specific UI
│   └── theme/            # Theme and styling
├── data/                 # Data layer
│   ├── repository/       # Repository implementations
│   ├── local/           # Local data sources
│   └── remote/          # Remote data sources
├── domain/              # Domain layer
│   ├── model/           # Domain models
│   ├── repository/      # Repository interfaces
│   └── usecase/         # Use cases
└── common/              # Common utilities
    ├── utils/           # Utility functions
    └── extensions/      # Extension functions

​

Naming Conventions

• Classes: PascalCase (MusicPlayer)
• Functions: camelCase (playMusic())
• Variables: camelCase (currentSong)
• Constants: UPPER_SNAKE_CASE (MAX_VOLUME)
• Packages: lowercase (com.musika.app.ui)

​

Testing

​

Unit Tests

• Write unit tests for business logic
• Test repository implementations
• Test use cases and utilities
• Aim for high code coverage

​

UI Tests

• Write UI tests for critical user flows
• Test different screen sizes and orientations
• Test accessibility features

​

Running Tests

./gradlew test

​

Documentation

​

Code Documentation

• Document public APIs with KDoc
• Add inline comments for complex logic
• Keep README files updated
• Document configuration changes

​

Release Process

​

Version Numbering

• MAJOR: Incompatible API changes
• MINOR: New functionality (backward compatible)
• PATCH: Bug fixes (backward compatible)

​

Release Checklist

• All tests pass
• Documentation is updated
• Changelog is updated
• Version numbers are bumped
• Release notes are prepared

​

Community Guidelines

​

Communication Channels

• GitHub Discussions: For general questions and discussions
• GitHub Issues: For bug reports and feature requests
• Pull Requests: For code contributions and reviews

​

Getting Help

1. Check the GitHub Discussions
2. Create a new discussion
3. Contact maintainers directly through GitHub

​

Recognition

• README.md contributors section
• Release notes
• GitHub contributors page
• App credits (if applicable)

​

Questions?

1. Check the GitHub Discussions
2. Create a new discussion
3. Contact maintainers directly