Colaborando con Cacao Accounting.

Gracias por su interes en colaborar con Cacao Accounting (el proyecto).

Licencia del Proyecto.

Cacao Accounting es sofware libre y de código abierto liberado bajo la licencia Apache Versión 2 (la licencia del proyecto), esto quiere decir que los usuarios del proyecto pueden:

• Usar el proyecto con o sin fines de lucro.
• Modificar el proyecto para ajustarlo a sus necesidades especificas (definiendo claramente los cambios realizados al proyecto original).

Sin embargo los usuarios no pueden:

• Hacer uso de las marcas registradas del proyecto sin permiso explicito.
• Requerir garantias de cualquier tipo; el proyecto se distribuye tal cual sin garantias de que pueda ser útil para algún fin especifico.

Certifica el origen de tus aportes.

Para incorporar tus aportes al proyecto requerimos que certifiques que el o los aportes son de tu propiedad o que tienes permiso de terceros para incorporar el o los aportes al proyecto, siguiendo el certificado de origen del desarrollador.

Recomendamos ejecutar:

git commit -s

Y se agregara una firma apropiada al commit, no se incluiran en el proyecto commits sin el correspondiente Sing-Off.

Colaborando con el proyecto

Formas de colaborar.

Pueden colaborar de distintas formas:

• Como desarrollador.
• Como control de Calidad (QA).
• Escribiendo y mejorando la documentación o el Manual de Usuario.
• Aportando ideas de nuevas caracteristicas.
• Reportando errores.
• Traduciendo.
• Brindando guía y soporte a otros usuarios.
• Compartiendo el proyecto con otros.

Al formar de la comunidad del proyecto debes seguir el código de conducta establecido.

Colaborando con el desarrollo del proyecto:

El desarrollo es multiplataforma, puedes utilizar tanto Windows, Linux o Mac para aportar el proyecto, para colaborar con el proyecto necesitas:

• GIT
• Yarn
• Python

La versión minima de Python soportada es: >=3.6

Tecnologías utilizadas:

• Backend: Flask.
• Frontend: Bootstrap 5.
• ORM: SQLAlchemy.

El desarrollo se realiza en la rama development, una vez el proyecto sea liberado para producción la rama main contendra la últma versión apta su uso en producción.

Obteniendo el codigo fuente:

Descarga el codigo fuente con:

git clone https://github.com/cacao-accounting/cacao-accounting.git
cd cacao-accounting

Para iniciar el proyecto es necesario seguir estos pasos:

Crear un entorno virtual de python.

python -m venv venv
# Windows:
.\venv\Scripts\activate.bat
# Linux y MAC: 
source venv/bin/activate 

Instalar las dependencias:

python -m pip install -r requirements.txt
python -m pip install -r development.txt
python setup.py develop
yarn

Yarn es necesario para no tener que incluir librerias JavaScritp de terceros en el repositorio principal del proyecto.

Puede verificar que la instalación fue correcta ejecutando:

cacaoctl
Usage: python -m flask [OPTIONS] COMMAND [ARGS]...

  Interfaz de linea de comandos para la administración de Cacao Accounting.

Options:
  --version  Show the flask version
  --help     Show this message and exit.

Commands:
  cleandb     Elimina la base de datos, solo disponible para desarrollo.
  db          Perform database migrations.
  initdb      Crea el esquema de la base de datos.
  routes      Show the routes for the app.
  run         Run a development server.
  serve       Inicio la aplicacion con waitress como servidor WSGI por...
  shell       Run a shell in the app context.
  version     Muestra la version actual instalada.

Esquema de la base de datos

Para crear una base de datos de pruebas ejecutar:

cacaoctl initdb

Ejecutar servidor de desarrollo:

Para acceder al proyecto podemos utilizar el servidor web de desarrollo incluido en flask:

FLASK_ENV=development  # Linux
set FLASK_ENV="development"  # Windows
cacaoctl run

Para verficiar que el proyecto se ejecuta correctamente con un servidor WSGI acto para producción ejecutar:

cacaoctl serve

El usuario de pruebas es cacao con contraseña cacao.

Guía de estilo:

Seguimos PEP8 con un largo de linea de 127 caracteres maximo.

Black es una excelente herramienta para dar formato a tu código antes de hacer commit de tus cambios.

Si usa VSCode puede configurar black para formatear sus cambios al guardar.

Pruebas automaticas:

Utilizamos flake8 y pytest para asegurar la calidad del código fuente del proyecto.

Recomendamos ejecutar antes de enviar tus cambios:

black cacao_accounting
flake8 cacao_accounting
pytest

Escribe un buen mensaje en tu commit

Agracedemos te tomes tu tiempo para escribir un buen mensaje en tus commit, recomendamos seguir este ejemplo de Chris Beams:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Otros ejemplos de buenos mensajes de commit se pueden encontrar aca:

• Buenas Practicas En Commits De Git
• How to Write a Git Commit Message

Utilizar Commits Convencionales:

Solicitamos su apoyo para adoptar Commits Convencionales:

 - build: Cambios que efectan la distribución del proyecto.
 - ci: Actualización a herramientas para pruebas automaticas.
 - docs: Actualizacion de la documentación.
 - feat: Agrega funcionalidades nuevas.
 - fix: Correción de errores.
 - gui: Cambios que afectan la interfaz de usuario pero no la logica de negocios.
 - refactor: Modificaciones que no agregan nuevas funciones o arreglan errores.
 - style: Correcciones de Estilo.
 - test: Cambios en pruebas unitarios.

Independientemente del tipo un commit con el texto BREAKING CHANGE, sin importar su tipo, se traducen a un cambio de versión MAJOR.

Versionado semantico

Para Cacao Accounting hemos adoptado versiones semanticas.

Mayor: Al ser una aplicación contable trabajamos con datos historicos, así que cualquier cambio en la estructura de base datos que agregue cambios no compatibles con versiones anteriores se debera considerar un cambio mayor y requerir un lanzamiento mayor. Una migración efectiva del esquema de la base de datos debe proveerse a los usuarios.

Menor: Lanzamiento de nuevas caracteristicas.

Path: Correciones menores.

Fix: Correción de errores criticos.

Ejecutar pruebas unitarias:

export CACAOTEST=True
pytest

Configurar Base de datos para pruebas

El proyecto se prueba con SQLite, MySQL 8, Postgresql 13 y MS SQL Server.

MySQL

Para crear una base de datos de pruebas ejecutar los siguientes queries en MySQL:

CREATE DATABASE IF NOT EXISTS cacao;
CREATE USER IF NOT EXISTS 'cacao' IDENTIFIED BY 'cacao';
GRANT ALL PRIVILEGES ON cacao.* TO 'cacao';
FLUSH PRIVILEGES;

Postgresql

Para crear una base de datos de pruebas ejecutar los siguientes queries en Postgresql:

CREATE DATABASE cacao;
CREATE USER cacao WITH PASSWORD 'cacao';
GRANT ALL PRIVILEGES ON DATABASE cacao TO cacao;

Pruebas de integración

Para vaidar que las vases de datos fueron creadas correctamente y la conexión es correcta ejecutar:

python tests\database.py
MySQL disponible
Postgresql disponible

Para ejecutar las pruebas ejecutar:

pytest tests\database.py

Empaquetar para distribución:

Para crear los archivos para distribuir el proyecto ejecutar:

python -m build
twine check dist/*
# Solo usuario con permisos de cargar en Pypi.
twine upload dist/*

Es un objetivo principal que el proyecto sea pip instalable así como ofrecer una versión del proyecto que pueda ser utilizada como aplicación de escritorio, para cumplir este objetivo hemos desarrollado open marquesote.

Varios

Estos son algunos tips a tomar en cuenta opcionalmente

Ignorar correcciones de estilo en git blame

git config blame.ignoreRevsFile .git-blame-ignore-revs