Saltar a contenido

Colaborando con Cacao Accounting.

PRs Welcome GitHub top language GitHub language count GitHub contributors GitHub last commit GitHub issues GitHub pull requests

SonarCloud

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

Licencia del Proyecto.

Cacao Accounting es software 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).
  • Distribuir el software original o modificado. Si distribuyen versiones modificadas, deben incluir una copia de la licencia y un aviso de los cambios realizados.

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.

Adicionalmente los usuarios deben incluir un aviso de copyright y la renuncia de responsabilidad cuando distribuyen el software, asegurando que se reconozca la autoría original.

La licencia Apache Versión 2 proporciona una concesión de derechos de patente, lo que significa que si un contribuyente aporta código, no puede demandar a los usuarios del software por infracción de patentes relacionadas con ese código, es porque que se solicita que los colaboradores del proyecto acepten el Acuerdo de Aceptación de la Licencia antes de incluir sus aportes en el proyecto.

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:

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:

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

Tecnologías utilizadas:

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 development.txt
python -m pip install -e .
cd cacao_accounting/static
npm install

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 serve

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:

bash run_test.sh

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:

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.
 - chore: Cambios que no afectan el funcionamiento del codigo fuente.

Independientemente del tipo un commit si este contiene 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:

bash run_test.sh
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;

Empaquetar para distribución:

El proyecto se debe publicar de forma automatica en PyPI si todas las pruebas automaticas pasan correctamente, solo se publica código de la rama main, el proceso fallara si no se actualizado la versión del proyecto (esto es un efecto esperado, no un error de configuración).

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.

Ignorar correcciones de estilo en git blame

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