Este repositorio es una plantilla con la estructura que utilizamos para documentar nuestros proyectos en Codeando. Si estás haciendo un proyecto de tecnología cívica puedes tomarla de guía o simplemente usar lo que necesites.
El nombre de nuestros repositorios está en español porque queremos ver más contenido en nuestro idioma. Si el nombre de tu proyecto tiene más de una palabra, es buena práctica que esté en minúsculas y separadas por guiones.
- ✅ estandar-datos-legislativos, aprende-con-datos, guia-participacion-digital.
- ❌ BlockchainForTheWin, OTRA_APP_DE_RAILS
‼️ En nuestros proyectos este archivo es obligatorio.- ℹ️ Este archivo debe llamarse README.md o LEEME.md y estar en la carpeta raíz del proyecto.
El archivo Readme contiene la información básica del proyecto. El archivo que estás leyendo ahora mismo es el Readme de este repositorio, y lo puedes tomar como referencia o ver el uso de los logos. Nuestros Readme contienen las siguientes secciones:
- Nombre del proyecto
- Descripción del proyecto en un tuit
- Acerca de: Describe en un máximo de 2 párrafos cortos el problema que buscas resolver
- Cómo comenzar: Describe como descargar, instalar y ejecutar. Si las instrucciones de instalación son extensas, puedes poner un resumen y enlazar a un manual de instalación.
- Cómo contribuir: Instrucciones para contribuir al proyecto, se enlaza al archivo
- Créditos: Quién mantiene y ha contribuido al proyecto
- Referencias
- Código de conducta: Enlace a nuestro código de conducta
- Licencia: Menciona la licencia utilizada y enlaza al archivo con la licencia completa
‼️ Esta sección es obligatoria en nuestros proyectos
Nuestra comunidad se basa en la colaboración, con personas de varios perfiles, instituciones, colectivos, movimientos. En tu sección de créditos menciona a quienes colaboraron en tu proyecto. Antes de incluir su nombre y contacto, es bueno preguntarle a la persona si quiere aparecer.
- ❗️Esta sección es opcional de acuerdo al proyecto.
Cuando uses metodologías de trabajo o contenido desarrollado por otras personas u organizaciones, puedes mencionarlo en esta sección. Por ejemplo: si usaste otro proyecto como referencia, documentos, otras ideas, etc.
‼️ Esta sección es obligatoria en nuestros proyectos- ℹ️ En caso de agregarlo como archivo debe llamarse CODE_OF_CONDUCT.md o CODIGO_DE_CONDUCTA.md y residir en la carpeta raíz del proyecto
El código de conducta nos permite crear espacios seguros y positivos para todas las personas que participan en el proyecto.
La última versión de nuestro código de conducta se encuentra en el repositorio de Comunidad y enlazamos directamente a él. Si tu proyecto es abierto, es bueno que establezcas un código de conducta, puedes usar el nuestro como referencia o aquí puedes consultar otras opciones:
- Código de conducta convenido para contribuyentes (Contributors Covenant)
- Geek Feminism 🇬🇧
- Mozilla Community Participation Guidelines 🇬🇧
- MediaWiki 🇬🇧
- Tactical Tech 🇬🇧
‼️ Este archivo es obligatorio en nuestros proyectos- ℹ️ Este archivo debe llamarse LICENSE o LICENCIA y estar en la carpeta raíz del proyecto
A diferencia del software propietario, como por ejemplo Microsoft Word, nuestros proyectos son de software libre. Esto quiere decir que publicamos los proyectos con una licencia que permite su copia, uso, modificación y redistribución sin limitaciones.
En algunos casos, un proyecto puede estar basado en otros proyectos o librerías de terceros, por es necesario revisar las licencias de estos proyectos o librerías para no incurrir en una violación de lo que ya establecieron.
Por ejemplo, el proyecto Decidim Monterrey está basado en el proyecto Decidim, y este se publica bajo la licencia GNU Affero General Public License v3.0, la cual especifica que si usas Decidim, tu proyecto debe ser liberado bajo la misma licencia.
Estos son algunos ejemplos de licencias que hemos usado en nuestros proyectos:
- MIT
- GNU Affero General Public License v3.0
- Creative Commons Attribution Share Alike 4.0 International
Si no sabes muy bien qué licencia elegir para tu proyecto, esta herramienta puede ser de ayuda.
‼️ Este archivo es obligatorio en nuestros proyectos- ℹ️ Este archivo debe llamarse CONTRIBUTING.md o CONTRIBUYE.md y residir en la carpeta raíz del proyecto
Trabajamos en abierto y por tanto es importante especificar de qué manera se puede colaborar. Estas instrucciones se especifican en un archivo que se llama CONTRIBUTING.md o CONTRIBUYE.md
Algunos ejemplos de referencia:
- ❗️ Este archivo es opcional en nuestros proyectos
- ℹ️ Este archivo debe llamarse HACKLOG.md o BITACORA.md y residir en la carpeta raíz del proyecto
Es buena práctica ir documentando los milestones, el contexto y los avances del proyecto en un archivo (HACKLOG.md). Esto permite que las distintas personas que colaboran en un proyecto puedan tener un lugar en donde de manera rápida y sencilla puedan entender qué objetivos, avances y cambios han ocurrido.
Otra buena práctica es documentar las tareas o issues que se estén trabajando haciendo uso de la herramienta de issues de GitHub.
‼️ Esta carpeta es obligatoria en nuestros proyectos- ℹ️ Esta carpeta debe llamarse
docs
La documentación del proyecto debe vivir en el mismo repositorio que el código. Los documentos que dan contexto o información adicional sobre el proyecto deben estar bajo esta carpeta. Pueden ser archivos markdown, word, pdf o txt.
Algunos ejemplos de documentos que pueden existir en esta carpeta:
- Documentación extendida sobre la instalación del proyecto (i.e. un manual de instalación)
- Legislación en la que está basada el proyecto (i.e. reglamento de participación ciudadana)
- Documentos de contexto (i.e. la forma en la que se distritó una ciudad para un proyecto)
‼️ Esta carpeta es OBLIGATORIA- ℹ️ Esta carpeta debe llamarse
recursos
Todos los recursos gráficos (logos, banners, etc) o fotografías deben de ir en la carpeta de recursos.
Creado con ❤️ por la comunidad de Codeando México.