Saltar al contenido principal
Versión: v0.8.0 🚧

Contribuir a Ambrosia POS

¡Gracias por tu interés en contribuir a Ambrosia POS! Nos encanta la colaboración comunitaria. Ya sea que estés corrigiendo un error, añadiendo una funcionalidad, mejorando la documentación o ayudando con el soporte a la comunidad, tu ayuda es bienvenida para construir el futuro de los pagos con Bitcoin.

Tabla de Contenidos​

Código de Conducta​

Este proyecto se adhiere a nuestro Código de Conducta. Al participar, se espera que cumplas con este código. Por favor, informa de comportamientos inaceptables a contact@ambrosiapay.com.

Primeros Pasos​

Requisitos Previos​

Antes de comenzar, asegúrate de tener instaladas las dependencias necesarias. Por favor, consulta nuestra Guía de Dependencias del Proyecto para instrucciones detalladas sobre la instalación de:

  • Java 21 (JDK)
  • Node.js
  • Docker
  • Gradle

Colaboradores por primera vez​

Si eres nuevo en el código abierto, echa un vistazo a:

Cómo Contribuir​

Tipos de Contribuciones​

Aceptamos varios tipos de contribuciones:

  • 🔍 Revisar nuestro código en GitHub

  • 🐛 Reportar errores o sugerir mejoras

  • 💡 Contribuir con ideas para nuevas funcionalidades

  • 🧪 Probar la beta e informar de problemas

  • 📝 Documentación: Mejorar nuestros documentos, README o comentarios de código

  • 🍴 Hacer un fork del repositorio y enviar tus Pull Requests (PRs)

Antes de Empezar​

  1. Busca problemas existentes para evitar duplicados.
  2. Discute cambios mayores abriendo un problema (issue) primero.

Configuración del Entorno de Desarrollo​

Una guía clara y ordenada para trabajar en Ambrosia‑POS usando herramientas nativas.

Requisitos:​

  • SDKMAN (oficial: https://sdkman.io/) 
    curl -s "https://get.sdkman.io" | bash
    source "$HOME/.sdkman/bin/sdkman-init.sh"
  • Java 21 (Temurin): 
    sdk list java
    sdk install java 21-tem
    java -version
  • Gradle: 
    sdk install gradle
    gradle -v
  • Node.js >= 18 y npm.
  • phoenixd (Lightning): 
    curl -fsSL https://raw.githubusercontent.com/olympus-btc/ambrosia-dev/master/scripts/install.sh | bash -s -- --yes

Verificación rápida​

java -version && gradle -v | head -n1 && node -v && npm -v

Pasos de Configuración​

  1. Haz un fork del repositorio en GitHub.

  2. Clona tu fork localmente:

    git clone https://github.com/TU-USUARIO/ambrosia.git
    cd ambrosia

  3. Paso 1 · Iniciar phoenixd Tras la instalación, asegúrate de que el servicio esté corriendo y que ~/.phoenix esté inicializado según la guía de Mastering phoenixd.

  4. Paso 2 · Servidor / Backend (Kotlin/Ktor):

    cd server
    ./gradlew run    # API en :9154
    • Tests: ./gradlew test

  5. Paso 3 · Cliente / Frontend (Next.js):

    cd client
    npm install
    npm run dev      # web en :3000
    • Lint: npm run lint
    • Tests: npm test

  6. Paso 4 · Configuración de Electron (Escritorio):

    cd electron
    npm install
    npm run dev

    (Consulta el README de Electron para más detalles)

Endpoints locales​

Solución de problemas​

Consejos
  • Usa el wrapper ./gradlew para evitar problemas de PATH.
  • Si algún puerto está ocupado, cambia 3000/9154 o detén el proceso en conflicto.
  • phoenixd: valida que corre y que ~/.phoenix contiene la configuración esperada.

Estándares de Código​

Guía de Estilo​

  • Cliente: Sigue las prácticas estándar de React/Next.js. Usa npm run lint para verificar problemas de estilo.
  • Servidor: Sigue las convenciones estándar de Kotlin.
  • Commits: Escribe mensajes de commit significativos.

Formato de Mensajes de Commit​

Recomendamos usar Conventional Commits:

tipo(ámbito): descripción

Ejemplos:

  • feat(auth): add login support
  • fix(server): resolve null pointer exception
  • docs(readme): update installation steps

Pruebas (Testing)​

Cliente (Frontend)​

Dentro de client/:

npm test

Servidor (Backend)​

Dentro de server/:

./gradlew test

Pruebas E2E​

El proyecto incluye pruebas de extremo a extremo (E2E) para la API del servidor escritas en Python. Para instrucciones detalladas, consulta el README de Pruebas E2E.

Proceso de Pull Request​

¿Cómo enviar un Pull Request?​

  1. Crea una rama para tu cambio (git checkout -b feature/funcionalidad-increible).
  2. Realiza tus modificaciones y haz commit de ellas.
  3. Ejecuta las pruebas para asegurar que no haya regresiones.
  4. Sube a tu fork y envía un Pull Request al repositorio principal.

Lista de verificación​

  • El código sigue las guías de estilo
  • Las pruebas pasan localmente
  • La documentación está actualizada si es necesario

Reporte de Problemas​

  • Reportes de Errores: Incluye pasos claros para reproducirlo, comportamiento esperado frente al real y detalles del entorno.
  • Solicitudes de Funcionalidades: Describe la funcionalidad propuesta, el caso de uso y la motivación.

Recursos de Desarrollo​

Estructura del Proyecto​

  • client/ - Aplicación frontend (Next.js/React).
  • server/ - Aplicación backend (Kotlin/Ktor).
  • electron/ - Envoltorio de escritorio (Electron).
  • doc/ - Documentación del proyecto.
  • scripts/ - Scripts de utilidad e instalación.

Comandos Útiles​

Servidor:

./gradlew run   # Ejecutar servidor
./gradlew jar   # Construir JAR

Cliente:

npm run dev     # Iniciar servidor de desarrollo
npm run build   # Construir para producción
npm start       # Iniciar servidor de producción

Comunidad​

¡Mantente conectado!

Síguenos en nuestras redes sociales y únete a la comunidad de desarrolladores y emprendedores que están construyendo el futuro de los pagos con Bitcoin.