Skip to content

Latest commit

 

History

History
568 lines (413 loc) · 23.2 KB

CONTRIBUTING.md

File metadata and controls

568 lines (413 loc) · 23.2 KB
Raw

Contribuyendo

Introducción

Antes que nada, gracias por considerar contribuir con esta iniciativa. Son las personas como tú las que hacen que sea una herramienta útil para estudiantes, profesores y tutores.

Esta guía está basada en esta y esta otra.

Al seguir estas guías estás comunicando que tú respetas el tiempo de las y los que estamos involucrados en esta iniciativa. A cambio, ellas y ellos deberían de forma recíproca resolver tus issues, revisar los cambios y ayudarte a finalizar tus pull requests.

¡Mantén la mente abierta! Mejorar la documentación sugiriendo nuevas entradas o reportar los errores que encuentres son ejemplos de contribuciones que ayudan a mejorar esta iniciativa.

Reglas de base

Esperamos que quienes quieran contribuir asuman las siguientes responsabilidades:

  • Asegurar la compatibilidad entre plataformas para cada cambio aceptado: Windows, Mac, Linux.
  • Crea issues para cualquier cambio mayor y mejora que desearías hacer. Discute las cosas de manera transparente y obtén los comentarios de la comunidad.
  • No agregues nuevos archivos a menos de que sea completamente necesario.
  • Mantén el versionamiento de las cosas que agregues tan cortos como sea posible.
  • Sé amable con las y los recién llegados y apoya la diversidad de nuevas y nuevos

contribuidores de todo tipo de antecedente. Revisa el código de conducta de la comunidad Python.

Tu primera contribución

¿Aún no sabes como empezar a contribuir? Puedes empezar revisando los

issues con etiquetas good first issue ‑principiante‑ y help wanted

  • Etiqueta good first issue: los issues con esta etiqueta deberían ser triviales de resolver, por ejemplo, un error ortográfico, o un error de formato.
  • Etiqueta help wanted: Estos son issues que pueden ser un poco más complicados que los anteriores.

Ambas listas de issues están ordenadas por la cantidad de comentarios que tienen. Aunque no es perfecto, la cantidad de comentarios es un proxy razonable para saber el impacto que tendrá el cambio.

No seas tímido. Tus comentarios y aportes son siempre bienvenidos. Puedes equivocarte, todos podemos equivocarnos, lo que no podemos hacer es dejar de aprender de nuestros errores, o ser negligentes; pero por lo demás, te alentamos a que pruebes.

PRs Welcome

Tip

¿Estás por hacer tu primer pull request? Aprende cómo hacerlo en esta serie gratuita How to Contribute to an Open Source Project on GitHub

En este punto, ¡ya estás preparada o preparado para hacer cambios! Siéntete libre de pedir ayuda; todos fuimos principiantes una vez 😸

Important

Si un colaborador te pide que hagas un rebase al pull request, se refiere a que muchísimo código ha cambiado y deberías actualizar la rama para que sea más fácil unirla al resto del código.

Empezando

Asumimos que si tienes acceso al repo puedes hacer todo lo que estás autorizado a hacer según los permisos de tu rol.

La rama main está configurada con una regla de protección de requiere:

  • Que haya un pull request para hacer un merge.
  • Que haya al menos una aprobación del pull request.
  • Que uno de los revisores sea code owner.

Tip

Para obtener más información sobre las reglas de protección de las ramas mira este link.

Para obtener más información sobre los code owners mira este link


Para cualquier cosa que sea mayor a una o dos líneas para corregir:

  1. Crea tu propio fork del código
  2. Haz los cambios en tu fork
  3. Cuando creas que los cambios ameritan ser incorporados en el repo:
    • Asegúrate de haber seguido el estilo de código del proyecto.
    • Envía un pull request solicitando que tus cambios sean incorporados.

Cómo reportar un bug

Cuando completes un issue para reportar un error, asegúrate de responder estas tres preguntas:

  1. ¿En qué página estabas navegando? Incluye la URL que muestra el navegador
  2. ¿Qué viste que consideras incorrecto?
  3. ¿Qué esperabas ver que consideras correcto?

Preguntas generales sobre el contenido deben ser planteadas a través de los canales de comunicación que proponen los profesores en los cursos o proyectos en los que se consume este contenido.

Cómo sugerir algo nuevo

En caso de que lo que quieras reportar no sea un error en un contenido existente sino la sugerencia de agregar un nuevo contenido, puedes hacerlo también a través de un issue.

Important

Cuando consideres que falta algo, probablemente no estés solo. Busca en la lista de issues si ya no existe uno similar al que estás considerando agregar; si no lo encuentras, crea uno nuevo.

Al crear un issue para pedir que se agregue el contenido que te gustaría ver, asegúrate de que incluya las respuesta a las siguientes preguntas:

  1. ¿Qué contenido está faltando? Incluye referencias a libros, sitios web, u otros recursos útiles para encontrar lo que estás sugiriendo
  2. ¿Por qué es necesario?
  3. ¿Cómo deberíamos agregarlo?

Convenciones

La documentación en este repo está creada utilizando el lenguaje Markdown. Es un lenguaje que permite crear texto con formato utilizando un editor de texto plano.

Mira los siguientes recursos para conocer más sobre este lenguaje:

Edición

Usamos Visual Studio Code para editar los archivos de este repo. Aunque puedes usar cualquier editor de texto, este documento asume que usas ese editor de código.

Tip

Como probablemente uses el editor en otros proyectos, considera crear un perfil antes de agregar estas extensiones que te sugerimos a continuación. Consulta este link para obtener más información sobre los perfiles en Visual Studio Code.

Instala las siguientes extensiones que son útiles para facilitar la edición:

Otras extensiones útiles:

  • Path Intellisense: Para auto-completar de nombres de archivos.
  • Rewrap: Para formatear el ancho del archivo a cierto número de columnas, que en nuestro caso es 80.
  • Numbered Bookmarks: Para navegar fácilmente dentro de un archivo mediante marcadores.
  • Print: Permite imprimir archivos Markdown.

Además, esta es la configuración sugerida del editor y sus extensiones:

{
  "files.autoSave": "afterDelay",
  "git.enableSmartCommit": true,
  "window.commandCenter": true,
  "cSpell.language": "en,es-ES",
  "editor.renderWhitespace": "selection",
  "editor.wordWrapColumn": 120,
  "markdown.validate.enabled": true,
  "markdown.updateLinksOnFileMove.enabled": "prompt",
  "rewrap.wrappingColumn": 80,
  "rewrap.autoWrap.enabled": true,
  "workbench.editor.untitled.hint": "hidden",
  "markdown.validate.enabled": true,
  "markdown.updateLinksOnFileMove.enabled": "prompt",
  "workbench.startupEditor": "none",
}

Organización del contenido

El contenido está organizado en estas carpetas:

  1. Entregable proyecto
  2. Técnicas y herramientas
  3. Plantillas
  4. Conceptos
  5. Unidades temáticas

Cada carpeta tiene un archivo Markdown ‑con extensión .md‑ cuyo nombre coincide con el de la carpeta y sirve como tabla de contenido de la carpeta ‑excepto que usa dos guiones bajos __ en lugar de uno para separar el número del resto de nombre; esto para que quede ordenado antes de los demás archivos‑: por ejemplo, la carpeta 4_Conceptos tiene un archivo 4__Conceptos.md.

Important

Mira la sección Nombres de archivos, más adelante en este documento, para conocer más detalles sobre las convenciones sobre los nombres de archivos y carpetas.

En algunas carpetas el contenido está organizado de manera jerárquica, pero no utilizamos sub carpetas, sino que agregamos niveles a los nombres de archivos: por ejemplo, el tema 5. Unidades temáticas tiene algunos de los siguientes niveles:

  • 5. Unidades temáticas
    • 5.1
      • 5.1.1
      • 5.1.2
    • 5.2
      • 5.2.1

Los nombres de los archivos en la carpeta 5_Unidades_tematicas comienzan con:

5_Unidades_tematicas

5__Unidades_tematicas.md

5_1__⋯.md

5_1_1⋯.md

5_1_2⋯.md

5_2__⋯.md

5_2_1⋯.md

Referencias a las fuentes

Respetamos la propiedad intelectual dando atribución al origen del contenido incluido en los documentos.

Cuando el contenido de un documento fue tomado de una fuente, incluimos el texto "Tomado de", seguido de una notas al pie, al final de la primera frase del documento.

Ejemplo

Esta es la plantilla para un requerimiento funcional o no funcional. Tomado de 1.

Fuente

Esta es la plantilla para un requerimiento funcional o no funcional. Tomado de [^1].

[^1]: Robertson, S. & Robertson, J. (2012). Mastering the Requirements Process:
Getting Requirements Right, 3<sup>rd</sup> Edition. Addison-Wesley Professional.

Note

Aunque las notas al pie aparecen al final del documento, en el documento en Markdown ponemos la referencia inmediatamente después de donde de usa, y no al final para que sea más fácil editar el documento.

En el caso de una imagen, el texto "Tomado de" va al final del pie de foto, seguido de una nota al pie.

Tip

Mira este link para tener más información sobre cómo crear notas al pie en Markdown.

Cuando usamos tablas en HTML no es posible agregar notas al pie. En ese caso las referencias las agregamos así:

Ejemplo

Ver debajo ↓

Robertson, S. & Robertson, J. (2012). Mastering the Requirements Process: Getting Requirements Right, 3rd Edition. Addison-Wesley Professional.↩︎

Fuente

<table>
    <tr>
        <td>
            Ver debajo <span id="back_ref_1"><a href="#ref_1">↓</a></span>
        </td>
      </tr>
</table>

-----

<span id="ref_1">Robertson, S. & Robertson, J. (2012). Mastering the
Requirements Process: Getting Requirements Right, 3<sup>rd</sup> Edition.
Addison-Wesley Professional.</span><a href="#back_ref_1" title="Volver...">↩︎</a>

Leyendas de figuras

Al incluir figuras en un documento las acompañamos de una pequeña leyenda debajo que explica o describe brevemente la figura. Esa descripción se utiliza también como como texto alternativo al embeber la imagen. Lo mismo hacemos con las tablas cuando resulta necesario o conveniente.

Estas leyendas las incluimos en itálica, asegurándonos de asociarles un número según la cantidad de figuras presentes hasta el momento en el documento, empezando por uno —1—. Si hay figuras y tablas en un mismo documento, las contamos por separado, por lo que puede haber una Tabla 1 y una Figura 1 en un mismo documento. Figura o Tabla se separa del resto de la leyenda por : —dos puntos—.

Antes de la imagen agregamos un elemento HTML anchor cuyo identificar id es figura o tabla, según corresponda, seguido del número respectivo. Esto permite hacer referencia a esa figura con [Figura N](#figura-n) como se muestra más abajo.

Al incluir las leyendas de las figuras y tablas de esta forma, podemos crear referencias desde dentro y fuera del documento.

Ejemplo

El ciclo de vida DAD

Figura 1: El ciclo de vida DAD.

§

Ver Figura 1.

Fuente

<a id="figura-1"/>

![El ciclo de vida DAD](/diagrams/DAD_Lifecycle.svg)

*Figura 1: El ciclo de vida DAD.*

§

Ver [Figura 1](#figura-1).

Note

Hay configurado un snippet figura para insertar el código necesario para incluir una figura.

Viñetas

Usamos el símbolo * para las viñetas; no usamos -.

Incisos

Cuando queremos incluir en una frase un texto en forma de aclaración o explicación ‑lo que en gramática se conoce como inciso‑, usamos ‑ que corresponde con la raya o EM DASH, código Unicode U+2014 o UTF-8 E28094; no usamos - o guión; una Github Action reemplaza ese carácter por NON-BREAKING HYPHEN, código Unicode U+2011 o UTF-8 E28091.

Puedes generar una raya:

  • En Windows: con Ctrl + Alt + -
  • En Mac: con Option + Shift + -

Palabras en inglés u otros idiomas

Cuando no existe una traducción ampliamente aceptada de una palabra en inglés u otro idioma al español, preferimos usar la palabra original; esa palabra la escribimos en cursiva.

Notas, consejos, avisos, etcétera

Incluimos notas ‑notes‑, consejos ‑tips‑, avisos ‑warnings‑, etc. usando la notación de citas en bloque según se describe aquí.

Ejemplo

Note

Destaca información que los usuarios deben tener en cuenta, incluso cuando hojean.

Tip

Información opcional para ayudar al usuario a tener más éxito.

Important

Información crucial necesaria para que los usuarios tengan éxito.

Warning

Contenido crítico que exige atención inmediata del usuario debido a riesgos potenciales.

Caution

Consecuencias potenciales negativas de una acción.


Fuente

> [!NOTE]
> Destaca información que los usuarios deben tener en cuenta, incluso cuando hojean.

> [!TIP]
> Información opcional para ayudar al usuario a tener más éxito.

> [!IMPORTANT]
> Información crucial necesaria para que los usuarios tengan éxito.

> [!WARNING]
> Contenido crítico que exige atención inmediata del usuario debido a riesgos potenciales.

> [!CAUTION]
> Consecuencias potenciales negativas de una acción.

Nombres de archivos

No usamos caracteres especiales o letras con tilde en los nombres de archivos.

Tampoco usamos espacios, separamos las palabras que componen el nombre con guión bajo _.

El nombre comienza con mayúscula.

TODOs

Para manejar la lista de TODO usamos la extensión Todo Tree que permite ver los TODO directamente en el editor.

También usamos la GitHub action TODO to Issue para convertir los nuevos TODO en issues.

Note

La línea que ves debajo y el texto que le sigue son la nota al pie que mostramos en la sección de referencias.

Footnotes

  1. Robertson, S. & Robertson, J. (2012). Mastering the Requirements Process: Getting Requirements Right, 3rd Edition. Addison-Wesley Professional. ↩