Skip to main content
We welcome contributions to MiTensión! This guide will help you get started with contributing code, reporting issues, and submitting pull requests.

​
Getting Started

1

Fork and Clone

Fork the repository and clone it to your local machine:
git clone https://github.com/your-username/mitension.git
cd mitension
2

Set Up Development Environment

Ensure you have the following installed:
  • Android Studio (latest stable version)
  • JDK 11 or higher
  • Kotlin 1.9.23
  • Android SDK 31+
3

Open Project

Open the project in Android Studio and let Gradle sync all dependencies.
4

Run the App

Build and run the app on an emulator or physical device to ensure everything works:
./gradlew assembleDebug

​
Project Structure

Understanding the project structure will help you navigate and contribute effectively.
app/src/
├── main/
│   ├── java/com/fxn/mitension/
│   │   ├── data/              # Database entities, DAOs, and repositories
│   │   ├── ui/
│   │   │   ├── screens/       # Compose UI screens
│   │   │   ├── theme/         # App theming and colors
│   │   │   └── viewmodel/     # ViewModels and UI state
│   │   ├── util/              # Utility classes and helpers
│   │   ├── alarm/             # WorkManager for notifications
│   │   ├── MainActivity.kt
│   │   └── MiTensionApplication.kt
│   └── res/
│       ├── values/            # Spanish strings (default)
│       ├── values-en/         # English strings
│       └── values-gl/         # Galician strings
├── test/                      # Unit tests
└── androidTest/               # Instrumented tests

​
Development Guidelines

​
Architecture

MVVM Pattern

Follow the Model-View-ViewModel architecture pattern used throughout the project.

Repository Pattern

Use the Repository pattern for data access. All database operations go through repositories.

Jetpack Compose

Build UI with Compose. Avoid mixing XML layouts with Compose.

Room Database

Use Room for data persistence. Update schema version when modifying entities.

​
Code Style

  • Follow Kotlin coding conventions
  • Use meaningful variable and function names in Spanish or English consistently
  • Add KDoc comments for public APIs and complex logic
  • Prefer immutability: use val over var when possible
  • Keep composables small and focused
  • Hoist state when necessary
  • Use remember and rememberSaveable appropriately
  • Pass callbacks for events, not ViewModels
  • ViewModels should NOT access Android resources directly (R.string, Context, etc.)
  • Use dependency injection or pass necessary data from UI layer
  • Expose UI state via StateFlow or State

​
Testing Requirements

All new features and bug fixes should include appropriate tests.

​
Unit Tests

Located in app/src/test/, unit tests verify business logic without Android dependencies. Technologies:
  • JUnit - Test framework
  • MockK - Mocking library
  • Turbine - Flow testing
  • kotlinx-coroutines-test - Coroutine testing
Run unit tests: 
./gradlew test
Example test structure: 
class MedicionViewModelTest {
    @Test
    fun `test measurement validation`() {
        // Arrange
        val viewModel = MedicionViewModel(repository)
        
        // Act
        viewModel.validateMeasurement(120, 80)
        
        // Assert
        assertTrue(viewModel.isValid)
    }
}

​
Instrumented Tests

Located in app/src/androidTest/, these tests run on Android devices or emulators. Technologies:
  • Compose Test Rule - UI testing for Compose
  • Espresso - Android UI testing
  • JUnit - Test framework
Run instrumented tests: 
./gradlew connectedAndroidTest

​
Internationalization

When adding new strings, you MUST provide translations for all supported languages.
MiTensión supports three languages:

Spanish (default)

res/values/strings.xml

English

res/values-en/strings.xml

Galician

res/values-gl/strings.xml
When adding a new string:
  1. Add the string to values/strings.xml (Spanish)
  2. Add English translation to values-en/strings.xml
  3. Add Galician translation to values-gl/strings.xml
See the Internationalization page for more details.

​
Submitting Changes

​
Pull Request Process

1

Create Feature Branch

Create a new branch for your feature or bug fix:
git checkout -b feature/your-feature-name
2

Make Changes

  • Write clean, well-documented code
  • Follow the architecture patterns
  • Add tests for new functionality
  • Update documentation if needed
3

Test Thoroughly

Run all tests before submitting:
./gradlew test connectedAndroidTest
4

Commit Changes

Write clear, descriptive commit messages:
git commit -m "Add feature: measurement export functionality"
5

Push and Create PR

Push your branch and create a pull request:
git push origin feature/your-feature-name
Include a clear description of:
  • What changes were made
  • Why the changes were necessary
  • Any related issues

​
PR Checklist

Before submitting your pull request, ensure:
  • Code follows project conventions and style
  • All tests pass (unit and instrumented)
  • New features include appropriate tests
  • All new strings are translated to Spanish, English, and Galician
  • No Android resources (R.string, etc.) accessed directly in ViewModels
  • Documentation is updated if needed
  • Commit messages are clear and descriptive

​
Reporting Issues

Bug Reports

When reporting bugs, include:
  • Device and Android version
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshots if applicable

Feature Requests

For feature requests, describe:
  • The problem it solves
  • Proposed solution
  • Any alternative approaches

​
Code Review

All submissions require review. We use GitHub pull requests for this purpose. Reviewers will check:
  • Code quality and adherence to conventions
  • Test coverage
  • Architecture compliance
  • Internationalization completeness
  • Performance implications
Be open to feedback and willing to make changes. Code review helps maintain code quality and knowledge sharing.

​
Questions?

If you have questions about contributing, feel free to:
  • Open a GitHub issue with the “question” label
  • Review existing documentation
  • Check closed issues for similar questions
Thank you for contributing to MiTensión!

Build docs developers (and LLMs) love

Get started for freeTalk to us