¿Por qué se necesita un fichero README en la raíz de un repositorio git?

El objetivo de este fichero es facilitar una guía rápida a los que acaban de descubrir nuestra aplicación, API o librería de cómo empezar a usarla. Es muy importante que vaya al grano, sea conciso y muy claro. Para extendernos y entrar en detalles está la documentación, a la que siempre podemos enlazar desde dentro de nuestro README.

Servicios como Github o Bitbucket disponen de una interfaz web para navegar por los repositorios git, ver el código fuente, ver la historia y hacer pull requests entre otras muchas opciones. Estos servicios han adoptado el convenio de mostrar en la página web de inicio del repositorio el contenido de este fichero.

¿Y si no trabajo con github ni bitbucket?

También debes tenerlo. Si trabajas tú sólo, para que te ayude a refrescar la memoria cuando pase el tiempo; y si trabajas con otras personas, para que cuando clonen el repositorio git sepan qué hacer.

¿Qué formatos soporta?

El fichero README puede ser redactado en diferentes formatos, el más sencillo de ellos es texto plano (.txt). Tanto Github como Bitbucket ofrecen un servicio adicional, y es que si el fichero está escrito en ciertos formatos, se convertirá a HTML y se mostrará bastante más legible en la web.

Aunque el formato más extendido es markdown, ambos servicios soportan diversos formatos:

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *