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:

• Formatos soportados por github: markdown, textile, mediawiki, org, creole, rdoc, asciidoc, por y rst
• Formatos soportados por bitbucket: markdown, textile, rst

Clonar un repositorio significa bajarse una copia completa del mismo a nuestro a ordenador. ¿Y qué quiere decir una copia completa, os preguntaréis? Pues significa que después de clonar un repositorio tendréis en vuestro ordenador toda la historia del repositorio, completa.

En consecuencia, podréis:

• Navegar por la historia del proyecto, viendo cómo ha evolucionado
• Ver los cambios que han ocurrido en el código
• Saber quién y cuándo ha modificado cada cosa
• Acceder a las ramas del proyecto y crear las vuestras propias
• Empezar a modificar el código, guardar los cambios y añadir vuestro trabajo al que ya existe

Y todo esto sin necesidad de estar conectados a internet. Sólo necesitaremos conexión a internet cuando queramos «compartir» nuestro trabajo con alguien más o queramos subir nuestro trabajo a un servicio como bitbucket o github.

Esta es una de las preguntas más habituales que nos hacéis en el curso casi antes de empezarlo.