Capod es una aplicación Android diseñada para complementar la experiencia de los AirPods, ofreciendo a los usuarios de Android funcionalidades similares a las nativas de iOS. Esta guía te mostrará cómo puedes contribuir al desarrollo de este proyecto de código abierto.

Introducción al Proyecto Capod

Capod proporciona una serie de características útiles para los usuarios de AirPods en dispositivos Android, incluyendo:

• Visualización del estado de la batería de los AirPods y su estuche.
• Monitorización del estado de carga.
• Funciones de reproducción automática y pausa.
• Gestión de la conexión de los dispositivos.
• Soporte para toda la gama de AirPods (Pro, Max) y auriculares Beats.

El código fuente principal se encuentra en el directorio app/src/main/java/eu/darken/capod/ y está desarrollado en Kotlin, utilizando la arquitectura moderna de Android y los componentes de Jetpack.

Configuración del Entorno de Desarrollo

Requisitos Previos

Para comenzar a contribuir, asegúrate de tener lo siguiente:

• Android Studio: La versión más reciente (se recomienda Arctic Fox o superior).
• Java Development Kit (JDK): Versión 17 o superior.
• Git: Sistema de control de versiones.
• Android SDK: Nivel de API 33 o superior.

Clonación e Importación del Proyecto

Primero, clona el repositorio a tu máquina local:

git clone https://gitcode.com/gh_mirrors/ca/capod.git
cd capod

Abre el proyecto en Android Studio:

• Selecciona "Open" o "Import Project".
• Navega hasta el directorio capod.
• Espera a que Gradle sincronice las dependencias.

Instalación de Dependencias

El proyecto utiliza Gradle para la gestión de la construcción. Las dependencias se descargarán automáticamente la primera vez que se abra el proyecto. Si experimentas problemas de red, considera configurar un espejo de repositorios para tu región.

Análisis de la Estructura del Proyecto

Módulos Principales

• app: Módulo principal de la aplicación, contiene la lógica de negocio.
• buildSrc: Scripts de construcción y gestión de versiones.
• fastlane: Configuraciones para la automatización de construcciones y publicaciones.

Directorios de Código Fuente Principales

app/src/main/java/eu/darken/capod/
├── core/           # Lógica de negocio central
├── main/           # Código relacionado con la interfaz principal
├── preferences/    # Gestión de ajustes y preferencias
├── widgets/        # Componentes para widgets de pantalla de inicio
├── notifications/  # Gestión de notificaciones
└── ui/             # Componentes de la interfaz de usuario

Estructura de Recursos

app/src/main/res/
├── drawable/       # Recursos gráficos
├── layout/         # Archivos de diseño
├── values/         # Cadenas de texto y estilos
└── xml/            # Archivos de configuración

Construcción y Pruebas

Compilación del Proyecto

Puedes compilar el proyecto en Android Studio de las siguientes maneras:

• Compilación de Depuración: Haz clic en el botón de ejecución ▶️ o usa el atajo Shift+F10.
• Compilación de Lanzamiento: Utiliza la tarea Gradle assembleRelease.
• Compilación de Pruebas: Ejecuta la tarea testDebugUnitTest.

Ejecución de Pruebas

El proyecto incluye pruebas unitarias y de integración:

# Ejecutar todas las pruebas
./gradlew test

# Ejecutar un módulo de prueba específico
./gradlew :app:testDebugUnitTest

Verificación de Calidad del Código

Se utilizan herramientas de análisis estático de Kotlin para mantener la calidad del código:

# Ejecutar verificación de código
./gradlew ktlintCheck

# Corrección automática de formato
./gradlew ktlintFormat

Detalles de Contribución

1. Reporte de Incidencias y Sugerencias

Si encuentras un error o tienes una sugerencia de funcionalidad, puedes contribuir de las siguientes maneras:

• Reporte de Errores: Abre una incidencia en la sección de Issues con una descripción detallada.
• Solciitud de Funcionalidades: Describe la funcionalidad deseada y sus casos de uso.
• Contribuciones de Traducción: Ayuda a mejorar el soporte multilingüe.

2. Flujo de Contribución de Código

Para enviar código a Capod, sigue estos pasos:

1. Haz Fork del Proyecto: Crea una copia del repositorio en tu cuenta de GitCode.
2. Crea una Rama: Basada en la rama main, crea una nueva rama para tu funcionalidad.
3. Desarrolla e Implementa: Escribe el código y añade las pruebas correspondientes.
4. Confirma tus Cambios: Sigue las convenciones de Conventional Commits.
5. Crea un Pull Request (PR): Describe los cambios realizados.

3. Convenciones de Código

• Utiliza el lenguaje de programación Kotlin.
• Adhiérete a las directrices de desarrollo de Android.
• Incluye comentarios y documentación necesarios.
• Escribe pruebas unitarias que cubran las nuevas funcionalidades.

Guía para el Desarrollo de Nuevas Funcionalidades

Módulo de Comunicación Bluetooth

Si deseas añadir soporte para un nuevo modelo de AirPods, necesitarás familiarizarte con el protocolo de comunicación Bluetooth:

• Archivo Clave: BluetoothManager.kt.
• Análisis de Dispositivos: DeviceParser.kt.
• Implementación del Protocolo: Consulta la implementación para dispositivos existentes.

Desarrollo de Componentes UI

Al añadir nuevos componentes de interfaz de usuario:

1. Crea el archivo de diseño en app/src/main/res/layout/.
2. Añade el ViewModel correspondiente en app/src/main/java/eu/darken/capod/ui/.
3. Sigue las especificaciones de Material Design.
4. Asegura la compatibilidad con los modos claro y oscuro.

Desarrollo de Widgets

Los widgets de la pantalla de inicio se encuentran en:

• Ruta del Código: app/src/main/java/eu/darken/capod/widgets/.
• Archivo de Configuración: app/src/main/res/xml/widget_info.xml.

Documentación y Localización

Contribuciones a la Documentación

• Documentación de Usuario: Ayuda a mejorar el archivo README y la documentación de ayuda.
• Documentación de Desarrollo: Añade comentarios de código para funcionalidades complejas.
• Documentación de API: Utiliza el formato KDoc para los comentarios de documentación.

Contribuciones de Traducción

El proyecto utiliza Crowdin para la gestión de idiomas:

1. Visita la página del proyecto en Crowdin.
2. Selecciona el idioma que deseas traducir.
3. Envía tus sugerencias de traducción.
4. Los archivos de traducción se encuentran en los directorios de idioma dentro de fastlane/metadata/android/.

Pruebas y Aseguramiento de Calidad

Pruebas Unitarias

• Utiliza JUnit 5 y MockK para las pruebas unitarias.
• Los archivos de prueba se encuentran en el directorio app/src/test/.
• Asegúrate de que las nuevas funcionalidades cuenten con la cobertura de pruebas adecuada.

Pruebas de Integración

• Emplea Espresso para las pruebas de UI.
• Los archivos de prueba se encuentran en el directorio app/src/androidTest/.
• Simula escenarios de interacción real del dispositivo.

Revisión de Código

Todos los Pull Requests pasan por una revisión de código, centrándose en:

• Calidad y mantenibilidad del código.
• Completitud y corrección de las funcionalidades.
• Impacto en el rendimiento y uso de memoria.
• Compatibilidad hacia atrás.

Proceso de Lanzamiento

Gestión de Versiones

• Los números de versión siguen el control de versiones semántico.
• La información de la versión se gestiona en version.properties.
• Los cambios se documentan en CHANGELOG.md.

Construcción y Lanzamiento

El proyecto utiliza Fastlane para automatizar el proceso de construcción:

• Archivo de Configuración: fastlane/Fastfile.
• Metadatos: fastlane/metadata/.
• Gestión de Capturas de Pantalla: Generación automática de capturas en múltiples idiomas.

Canales de Distribución

• Google Play: Canal principal de distribución.
• GitHub Releases: Publicación de versiones de código abierto.
• F-Droid: Tienda de aplicaciones de código abierto.

Comunidad y Soporte

Obtener Ayuda

• GitHub Issues: Para discusiones técnicas y de funcionalidades.
• Comunidad de Discord: Para comunicación en tiempo real y soporte técnico.
• Recursos de Documentación: Documentación del proyecto y guías de desarrollo.

Beneficios para Contribuidores

• Los contribuidores se listarán en el archivo README.
• Los contribuidores significativos pueden recibir permisos de mantenedor.
• Participa en las discusiones sobre la dirección futura del proyecto.

Recomendaciones de Buenas Prácticas

Calidad del Código

1. Mantén la Simplicidad: Cada función debe realizar una única tarea.
2. Manejo de Errores: Gestiona adecuadamente las excepciones y casos límite.
3. Optimización del Rendimiento: Presta atención al uso de memoria y al consumo de batería.
4. Compatibilidad: Soporta Android 8.0 (API nivel 26) y versiones superiores.

Flujo de Desarrollo

1. Confirmaciones Pequeñas: Cada commit debe resolver un único problema.
2. Pruebas Exhaustivas: Escribe pruebas para garantizar la estabilidad de las funcionalidades.
3. Actualización de Documentación: Mantén la documentación relevante actualizada.
4. Revisión de Código: Participa activamente en las revisiones de código.

Comunicación y Colaboración

1. Descripciones Claras: Proporciona detalles completos en issues y PRs.
2. Respuesta Oportuna: Mantente al tanto de las actividades del proyecto y las discusiones.
3. Respeto Mutuo: Mantén un ambiente de comunicación amigable y abierto.

Inicia tu Viaje de Contribución

¡Ahora tienes toda la información necesaria para contribuir a Capod! Ya sea que quieras corregir un pequeño error, añadir una nueva funcionalidad o mejorar la documentación, tu contribución ayudará a millones de usuarios de AirPods a tener una mejor experiencia en sus dispositivos Android. Desde hoy, elige un área que te interese, haz fork del proyecto, crea una rama y ¡empieza a codificar! Recuerda que el crecimiento de la comunidad de código abierto depende del esfuerzo de cada contribuidor.

¡Actúa ahora!

• Clona el proyecto a tu máquina local.
• Selecciona un issue sencillo para empezar.
• Escribe el código y envía un PR.
• Participa en las discusiones de la comunidad.

¡Hagamos que Capod sea aún mejor juntos!