diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..a8aca91 --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,187 @@ + + +# FixCache + +- [Introducción](#Introduction) +- [Instalación](#Installation) +- [Permisos](#Permissions) +- [Configuración](#Configuration) +- [Desplegar tu propio FixCache](#Deploying-your-own-FixCache) + +## Introducción + +**FixCache** es una implementación de aplicación de GitHub de [FixCache](https://people.csail.mit.edu/hunkim/images/3/37/Papers_kim_2007_bugcache.pdf) con historial de commits de Git. + +FixCache puede ser útil para priorizar los recursos de verificación, validación y pruebas en los archivos más propensos a errores. + +Mantiene un registro de los commits de corrección de errores enviados a una `rama rastreada` [configurable](#Configuration) de un repositorio y mantiene una caché de tamaño fijo de entidades de archivos más propensas a errores. Los commits de corrección de errores se identifican mediante las `palabras clave de corrección` proporcionadas en la [configuración](#Configuration). + +En las pull requests, recupera la caché y actualiza las pull requests con información sobre los archivos presentes en la caché si la pull request actualiza dichos archivos. +- agrega la etiqueta `fix cache` a la pull request. +- agrega un comentario con los nombres de los archivos presentes en la caché y el número respectivo de consultas en caché (cache hits). + +![screenshot](assets/screenshot.png) + +El algoritmo se ejecuta sobre el historial de commits del proyecto. El artículo asume cuatro tipos de localidad donde ocurren los errores: + +- *Localidad de entidad cambiada*: si una entidad fue modificada recientemente, tenderá a introducir errores pronto +- *Localidad de nueva entidad*: si se ha añadido una entidad recientemente, tenderá a introducir errores pronto +- *Localidad temporal*: si una entidad introdujo un error recientemente, tenderá a introducir otros errores pronto +- *Localidad espacial*: si una entidad introdujo un error recientemente, las entidades "cercanas" también tenderán a introducir errores pronto + +## Instalación + +- Instálalo en tus repositorios desde [aquí](https://github.com/apps/fixcache) + +## Permisos + +### Permisos de repositorio + +La aplicación tiene acceso a los siguientes permisos de repositorio: + +- *Contenido*: `Solo lectura` +- *Metadatos*: `Solo lectura` +- *Pull requests*: `Lectura y escritura` + +### Eventos + +La aplicación está suscrita a los siguientes eventos: + +- `Pull request` +- `Push` + + +## Configuración + +La aplicación (por ahora) utiliza un archivo `.env` para la configuración. Se muestra una configuración de ejemplo en `env.sample`. + +### Configuración de GitHub + +- `GITHUB_APP_ID`: el id de la aplicación de GitHub +- `PRIVATE_KEY_PATH`: la ruta a la clave privada +- `WEBHOOK_SECRET`: la clave secreta del webhook para el webhook de la aplicación + +### Configuración de la caché de corrección + +- `CACHE_SIZE`: el tamaño de la caché de corrección, es decir, el número de archivos almacenados en la caché +- `HISTORY_SIZE`: el número de días desde los cuales cargar el historial de commits en la instalación +- `FIX_KEY_WORDS`: Palabras clave en un commit de corrección, por ejemplo, fix,fixed +- `TRACKED_BRANCH`: la rama principal para rastrear los pushes +- `SKIP_PATHS`: rutas a omitir/no almacenar en la caché de corrección, como archivos de pruebas + +### Valores predeterminados + +Los siguientes valores predeterminados se utilizan en la versión actual de la aplicación: + +- `CACHE_SIZE`: `25` +- `HISTORY_SIZE`: `30` +- `FIX_KEY_WORDS`: `fix` +- `TRACKED_BRANCH`: `master` +- `SKIP_PATHS`: `test,.md` + +Si esta configuración no es adecuada para tus repositorios, puedes [desplegar tu propio FixCache](#Deploying-your-own-FixCache) con la configuración requerida. + +## Desplegar tu propio FixCache + +FixCache se despliega en [Deta Micros](https://deta.sh). Los siguientes pasos muestran cómo desplegar tu propio FixCache como una aplicación de GitHub con una configuración personalizada. + +### Clonar el repositorio + +- Clona el repositorio con `git clone https://github.com/aavshr/fixCache.git`. + +### Desplegar en Deta + +Este despliegue es para [Deta Micros](https://deta.sh). Necesitarás haberte registrado en Deta y tener instalada la CLI de Deta. + +Si deseas desplegar en otra plataforma, necesitarás modificar ligeramente el código y luego configurar la configuración respectiva para el despliegue en otras plataformas. + +- Después de clonar el repositorio, cambia al directorio clonado e ingresa en tu terminal: + +```shell +$ deta new +``` + +Deberías ver en la salida que la aplicación ha sido creada y las dependencias han sido instaladas. + +- Después de instalar la aplicación, ingresa: + +```shell +$ deta details +``` + +Deberías ver los detalles de tu aplicación en la salida. El `endpoint` mostrado se necesitará más tarde para agregarlo como la URL del webhook en nuestra aplicación de GitHub. + +- Finalmente, deshabilita la autenticación ingresando: + +```shell +$ deta auth disable +``` + +Utilizaremos una clave secreta del webhook para verificar que los eventos provienen de GitHub en nuestro endpoint del webhook. + +### Crear una aplicación de GitHub + +Una guía completa sobre cómo crear una aplicación de GitHub está disponible [aquí](https://docs.github.com/en/developers/apps/building-github-apps). + +- Ve a tus *configuraciones de desarrollador* (están bajo *configuraciones* en el menú desplegable cuando haces clic en tu perfil en GitHub) y crea una nueva aplicación de GitHub. Proporciona un nombre (y una descripción si lo deseas). + +### Configurar el webhook + +En *Webhook URL*, escribe el *endpoint* obtenido de la salida de `deta details`. + +Genera una cadena aleatoria larga y segura (hay servicios en línea que hacen esto) y úsala como *Webhook Secret*. Guarda esta clave secreta, ya que la necesitarás para [configurar la aplicación](#Configure-the-app) más tarde. + +### Permisos y Eventos + +Al elegir los permisos para la aplicación, deberás proporcionar los siguientes *permisos de repositorio*: + +- *Contenido*: `Solo lectura` +- *Metadatos*: `Solo lectura` +- *Pull requests*: `Lectura y escritura` + +La aplicación está suscrita a los siguientes eventos: + +- `Pull request` +- `Push` + +### Generar la clave privada + +Después de crear la aplicación de GitHub, ve a la configuración *General* de tu aplicación y genera una clave privada. + +Guarda la clave privada en un archivo dentro de tu directorio clonado. Esto es requerido para la autenticación. + +Asegúrate de **no hacer commit** de este archivo en un repositorio público. + +### Configurar la aplicación + +La configuración de la aplicación (por ahora) se realiza simplemente a través de variables de entorno. Crea un nuevo archivo `.env` en el directorio clonado y proporciónale las siguientes variables. +Se proporciona un archivo de ejemplo `env.sample` en el repositorio para ver el formato del archivo. Asegúrate de **no exponer** públicamente tu archivo `.env`. + +- `GITHUB_APP_ID`: el id de la aplicación de GitHub, puedes encontrarlo en la configuración general de tu aplicación de GitHub. +- `PRIVATE_KEY_PATH`: la ruta al archivo de clave privada que guardaste en el paso anterior. +- `WEBHOOK_SECRET`: la clave secreta del webhook para el webhook de la aplicación +- `CACHE_SIZE`: el tamaño de la caché de corrección, es decir, el número de archivos almacenados en la caché +- `HISTORY_SIZE`: el número de días desde los cuales cargar el historial de commits en la instalación +- `FIX_KEY_WORDS`: Palabras clave en un commit de corrección separadas por comas, por ejemplo, fix,fixed +- `TRACKED_BRANCH`: la rama principal para rastrear los pushes +- `SKIP_PATHS`: rutas a omitir/no almacenar en la caché de corrección, como archivos de pruebas + +### Desplegar los cambios y la configuración + +Primero cambia al directorio raíz del directorio clonado (si no estás ya allí) y despliega los cambios con: + +```shell +$ deta deploy +``` + +A continuación, despliega la configuración del `.env` con: + +```shell +$ deta update -e .env +``` + +Deberías ver que las variables de entorno se han actualizado correctamente. + +### Instalación + +FixCache ahora debería estar completamente desplegado y listo para funcionar. Puedes instalar la aplicación en tus repositorios en la página *Install App* de tu aplicación de GitHub.