Resumen

Este libro contiene algunas cosas que se deben y no se deben hacer para el software de Código Abierto.

Prefacio

La comunidad de Código Abierto está prosperando. Cada día crece el número de proyectos de Código Abierto, al igual que el ejército de contribuyentes que los mantienen. Si bien esto es emocionante para la industria, puede ser desalentador para un desarrollador nuevo en la comunidad. Este libro tiene como objetivo proporcionar algunos consejos para los recién llegados para ayudarlos a evitar las trampas del desarrollo de Código Abierto y aprender de la sabiduría colectiva de la comunidad.

Como dice el proverbio antiguo, "El tiempo y la marea [y la tecnología] no esperan a nadie". Y para lo mejor de nuestra capacidad, tampoco este libro. ¡Recuerde verificar el número de la versión para las actualizaciones! Estamos actualmente en la versión 0.1.17.

Nos encantaría su ayuda para mantener este libro actualizado. Sus comentarios, sugerencias y pull requests son bienvenidos. Puede encontrar el repositorio en GitHub: https://github.com/eddiejaoude/book-open-source-tips.

Si tiene alguna pregunta, por favor comuníquese con el autor, Eddie Jaoude en https://twitter.com/eddiejaoude.

Introducción

El Código Abierto está dominando la industria del software. Sus campeones incluyen conocidas organizaciones como Facebook, Twitter, Netflix, LinkedIn y Google (Android/Chrome), pero más importantemente, un ejército de desarrolladores individuales apasionados alrededor del mundo. Sus esfuerzos han impactado casi todas las partes de la ciencia de la computación, culminando en millones de proyectos de código abierto, ¡con miles de millones de líneas de código!

Si bien este ecosistema abundante ha sido de gran beneficio para toda la industria, también puede hacer que sea difícil para los recién llegados saber por dónde empezar. Si usted es un recién llegado, es posible que se enfrente a preguntas tales como "¿Cómo puedo contribuir a la comunidad de código abierto?" O, "¿Cómo elijo entre tantos proyectos en competencia?". Los siguientes puntos a abordan algunas de esas preguntas básicas, además de algunos consejos para aspirantes a desarrolladores de código abierto.

Vamos a sumergirnos en esto.

SUGERENCIA: Los proyectos que no se hacen públicos al principio tienen un mayor riesgo de tener credenciales privadas comprometidas en la historia. Por lo tanto, se recomienda altamente hacer públicos los proyectos desde el principio, y afirmar que no están terminados no es una excusa, ya que nunca se terminarán. Si es público desde el primer día, se usa la mentalidad correcta y, por lo tanto, se reduce el riesgo.

Qué Hacer

Archivo Readme

La documentación es algo que suele dejarse para el final. Comienza cada proyecto con, al menos, un archivo README.md con información básica, por ejemplo, una descripción y guía de inicio rápido, si cambias alguna característica o funcionalidad, intenta al menos actualizarlo en conjunto con tus commits.

Ejemplo README.md

# Nombre del Proyecto

Incluye cualquier identificación del proyecto (ej. CI) aquí al comienzo.

Descripción del proyecto y sus objetivos.

Incluye también lo que no hace.


## Capturas de pantalla

Nada dice más que las capturas de pantalla.


## Dependencias

Cualquier dependencia requerida por el proyecto.


## Instalación

Cómo instalar en Mac...

Cómo instalar en Linux...

Cómo instalar en Windows...


## Uso

Cómo utilizar el proyecto


## Configuración de Contribuciones

Si la gente quiere contribuir, qué pasos deberían seguir.

Resumen y enlace al archivo `CONTRIBUTION.md` con más detalles.


## Código de Conducta

Resumen del Código de Conducta, con un enlace a `CODE_OF_CONDUCT.md`.


## Registro de Cambios / Historial de Versiones

Versión principal y cambios importantes.


## Meta data

Cualquier otra información útil.

Bloque de código

Utilice el resaltado de sintaxis dentro de los bloques de código en la documentación para que sea más fácil de leer.

Resaltado de sintaxis de Github
Resaltado de sintaxis de Github

Archivo de contribución

Uno de los principales beneficios de un proyecto de Código Abierto y sus contribuciones a la comunidad. Baje la barrera para entrar con un archivo CONTRIBUTING.md en la raíz de su proyecto de Código Abierto. Obtenga más información sobre Archivo de contribución de GitHub

Muchas veces los proyectos de código abierto colocan un archivo CONTRIBUYENTE en el directorio raíz. Explica cómo un participante debe hacer las cosas, como código de formato, correcciones de prueba y enviar parches. Aquí hay un buen ejemplo de puppet y otro de factory_girl_rails. Desde el punto de vista de un mantenedor, el documento comunica de manera sucinta la mejor manera de colaborar. Y para un colaborador, una revisión rápida de este archivo verifica que su presentación sigue las pautas del mantenedor.
— GitHub
Pautas de Contribución de GitHub
Pautas de Contribución de GitHub
Pautas de Contribución de GitHub

Explora proyectos de código abierto

Recuerde explorar otros proyectos de código abierto para ver cómo otros proyectos se han administrado con éxito y cuáles fueron sus resultados.

Aquí hay 10 ejemplos de proyectos de código abierto para comenzar:

CONSEJO: Cuantos más proyectos de código abierto haya explorado, más verá qué prácticas han funcionado y cuáles no. Esto le proporcionará más conocimiento sobre cómo le gustaría ejecutar su proyecto en la práctica, en función de los proyectos existentes que haya conocido.

Código de Conducta

Su comunidad necesita sentirse segura, diversa e inclusiva. Asegúrese de tener un Código de Conducta para su proyecto y comunidad. Lea más acerca de Convenio de Colaboradores: Un Código de Conducta para Proyectos de Código Abierto

El código abierto siempre ha sido la base de Internet, y con la llegada de las redes sociales de código abierto, esto es más cierto que nunca. Pero los proyectos gratuitos, libres y de código abierto sufren de una sorprendente falta de diversidad, con una participación dramáticamente baja de mujeres, personas de color y otras poblaciones marginadas.
— Convenio de Colaboradores
Breve reseña del problema
Una forma fácil de comenzar a abordar este problema es ser abiertos en nuestra receptividad, dándole la bienvenida a todas las personas para que contribuyan y comprometiéndonos a cambio de valorarlas como seres humanos y fomentar una atmósfera de bondad, cooperación y comprensión.
— Convenio de Colaboradores
Breve reseña de la solución

Plantillas de Github

Las plantillas de Issue y Pull Request realmente ayudan a mantener el proyecyo consistente y recuerdan a las personas no dejar afuera cierta información útil.

Para agregar una plantilla de Issue a un repositorio cree un archivo llamado ISSUE_TEMPLATE en el directorio raíz. Una extensión de archivo es opcional, pero los archivos Markdown (.md) son soportados. El soporte para Markdown hace más fácil agregar cosas como títulos, enlaces, @-menciones, y listas de tareas a tus plantillas.
— GitHub
Plantilla para Issue de GitHub
Las plantillas para Pull Request siguen el mismo patrón: agrega un archivo denominado PULL_REQUEST_TEMPLATE al directorio raíz de tu repositorio.
— GitHub
Plantilla para Pull Request de GitHub
Si te preocupa la desorganización creada en el directorio raíz de tu proyecto, también hemos agregado soporte para una carpeta .github/. Puedes poner los archivos CONTRIBUTING.md, ISSUE_TEMPLATE.md, y PULL_REQUEST_TEMPLATE.md en .github/ y todo seguirá funciona como estaba previsto.
— GitHub
Directorio Oculto de GitHub para Plantillas

Detalles completos de GitHub para ayudar a las personas a contribuir en tu proyecto

Licenciamiento

No es requerido seleccionar una licencia, sin embargo, al hacerlo, estás seleccionando "Sin Licencia" lo que por defecto te llevará a los Términos y Condiciones de GitHub. GitHub ha creado un gran sitio web informativo para ayudarte a elegir una licencia

A continuación ejemplos de "Escoge una licencia de código abierto":

La Licencia MIT es una licencia permisiva que es breve y va directo al grano. Permite a la gente hacer lo que deseen con tu código siempre y cuando recibas atribución y no te hagan responsable.
— Escoge una Licencia
Licencia MIT
Note
jQuery, .NET Core, y Rails utilizan la Licencia MIT.
La Licencia Apache 2.0 es una licencia permisiva similar a la licencia del MIT, pero además provee una otorgamiento expreso de derechos de patente de los colaboradores a los usuarios.
— Escoge una Licencia
Licencia Apache 2.0
Note
Android, Apache, y Swift utilizan la Licencia Apache 2.0.
La GNU GPLv3 es una licencia copyleft que requiere que cualquiera que distribuya tu código o un trabajo derivado haga lo mismo con el código fuente bajo los mismos términos, y también provee una otorgamiento expreso de derechos de patente de los colaboradores a los usuarios.
— Escoge una Licencia
GNU GPLv3
Note
Bash, GIMP, y Privacy Badger utilizan la Licencia GNU GPLv3.
Cuando realizas un trabajo creativo (que incluye código), tu trabajo está bajo copyright exclusivo por defecto. A menos que incluyas una licencia que especifique lo contrario, nadie más puede usar, copiar, distribuir, o modificar tu trabajo sin correr el riesgo de bajas, sacudidas o litigios. Una vez que tu trabajo tiene otros colaboradores (cada uno un titular de derechos de autor), "nadie" comienza a incluirte a ti.
— Escoge una Licencia
Sin Licencia
Caution
Como consumidor, si encuentras software que no contiene una licencia, eso generalmente significa que no tienes permiso de los creadores para usar, modificar, o compartir el software. A pesar de que un alojador de código como GitHub pueda permitirme ver y bifurcar -fork- el código, esto no implica que tú tienes el permiso de usar, modificar, o compartir el software para ningún propósito. Tus opciones son: Pide amablemente a los desarrolladores que agreguen una licencia, no utilices el software, negocia una licencia privada con un abogado.

Git commit

Los commits en Git deben ser pequeños y atómicos, ya sea un pequeño cambio o característica. Esto hará tus mensajes de commit más fáciles de escribir y los cambios se agruparán localmente. Hay varios beneficios a esto:

  • Revisar el historial será claro y fácil de entender

    • si quieres encontrar algo

    • deshacer / remover algún trabajo

  • Automatizar la generación del registro de cambios como parte de tu versión para etiquetar y empaquetar, etc

Mensaje de commit

  • Limita el mensaje de asunto a 50 caracteres

  • No finalices el mensaje con un punto ..

  • Si precisas más de 50 caracteres utiliza el cuerpo (descripción)

  • Limita el cuerpo a 72 caracteres

  • Utiliza el cuerpo para explicar porqué no cómo, esto puede verse en tu código

Más información en Git Commit

Tip
Antes de realizar el commit, chequea el git diff para asegurarte que no estás commiteando algo que no quieres, o que no debería serlo.

Little and often

Steady projects are not only more stable, but are generally more successful & are better for your health. Trying doing a little every day or week.

Working frequently on your project gives your community confidence that you believe in your project & are in it for the long term not just that moment.

Planifica

Crea tareas hoy en preparación para el mañana. Esto tiene dos beneficios, te permite en un futuro comenzar a trabajar de manera inmediata, y digerir las tareas por la noche cuando tal vez realices los últimos retoques.

Tip
Planifica para un futuro próximo, no muy lejano, ya que las cosas pueden cambiar

GitHub Issue / Tarea

Mantenlos pequeños. Abordar un trabajo extenso siempre es abrumador y difícil de encontrar un buen momento. Mientras más pequeñas las tareas, más probabilidades tendrán de ser resueltas y el riesgo será menor. Pero recuerda que las tareas deben aportar valor al proyecto.

Incluye diagramas, capturas de pantalla, sub-tareas y cualquier elemento visual que ayude a describir el issue y los cambios.

Tip
No olvides que puedes utilizar un checklist para las sub-tareas en GitHub Issues Checklist. Las listas de sub-tareas son antepuestas por [ ] para items incompletos y [x] para items completos.

Siempre responda - Issue y Pull Request

Responda siempre a un Issue y Pull Request de manera oportuna, idealmente dentro de 24 horas (incluso si se trata de un comentario que confirma que al menos ha leído el problema y responderá completamente en 3 días). Esto maneja las expectativas de cuándo el contribuyente puede esperar una respuesta completa.

Pull Requests

Si te has tomado el tiempo de realizar el trabajo, asegúrate de agregar una descripción a tu Pull Request para facilitar la tarea de procesar lo que has hecho a quien lo revise. Crea un Issue primero para que un plan de trabajo pueda ser discutido antes de que comiences el trabajo y para recordarte a ti mismo las metas propuestas en la tarea.

Los Pull Requests deberían estar enlazados al Issue original que intentan resolver. Esto puede realizarse utilizando un # seguido de Issue No, por ejemplo: #123. La descripción del Issue contendrá la información previa a los cambios, por consiguiente, la descripción del Pull Request deberá contener la información posterior a los mismos. Incluye material visual también, por ejemplo, diagramas y capturas de pantalla.

Recuerda, mantenlo conciso. Por ejemplo, si tus cambios contienen una característica o arreglo de un bug y cambios de estilo, éstos deberían estar en Pull Requests separados. Es mejor que cada proyecto tenga 10 Pull Requests, que 1 o 2 Pull Requests masivos.

Tip
Los Pull Request deberían ser una característica o cambio individual.

Múltiples commits en un Pull Request resaltan la creación de pasos en el Pull Request. No intentes hacer todo en un solo commit.

Los comentarios importan, si estás en duda, agrégalo, pueden ser removidos con más facilidad que agregados. No describas el cómo, eso obviamente se encuentra en el código, describe el porqué.

Revisión

Incluso si eres sólo tú en el proyecto, intenta crear Pull Requests y pide a un amigo que lo revise. Esta aproximación es invaluable ya que un segundo par de ojos encuentra con frecuencia las omisiones.

Tip
Incluso los cambios de texto simples pueden tener sentido para tí pero no para alguien más. ¡Revisa todo!

Automatización - Pruebas, Integración continua (IC), Despliegue Continuo (DC)

¡Automatice todo! Esto ayuda a reducir la barrera para entrar y aumentar la repetibilidad.

  • Las pruebas automatizadas tienen muchos beneficios y dan confianza en el estado y la calidad de la aplicación:

    • Las pruebas unitarias son excelentes para el diseño y la arquitectura de la funcionalidad

    • Las pruebas de integración son geniales para los puntos de contacto

    • Las pruebas de extremo a extremo son excelentes para realizar pruebas completas de aplicaciones y simular al usuario

  • Debería ser muy fácil configurar un entorno local y ejecutar todas estas pruebas

  • Ejecute las pruebas automatizadas en Integración continua (IC) después de que alguien haya introducido sus cambios de código en una rama específica

  • Cuando las pruebas automáticas son exitosas, implemente la aplicación conocida como Entrega Continua (ED)

NOTA: Esto incluye migraciones de esquema de bases de datos, creación de activos estáticos y cualquier cosa que requiera el producto final

CONSEJO: TravisCI es muy recomendable en proyectos de código abierto. Muy fácil de instalar y poner en marcha, todo desde un simple archivo `yamla.

Prototipando - Consigue rápidamente un prototipo para tus usuarios

Consigue feedback tan pronto como sea posible. Provee un prototipo rápido a tus usuarios para obtener feedback y dirección instantáneos. Recuerda dejar en claro que es un prototipo.

Tip
Cuando construyes un prototipo, la tecnología que eliges es menos importante con respecto a la longevidad que a la rapidez y posibilidad de testear nuestra potencial solución tecnológica.

Tiempo óptimo - trabaja en tu mejor momento

Las personas trabajan mejor en diferentes momentos del día y la noche, así que intenta encontrar tu momento más eficiente y óptimo. Incluso si es a las 11pm en la noche o las 4am, trata de utilizar tu momento más productivo.

Sin tiempo suficiente

Todos tenemos las mismas 24 horas disponibles en el día para nosotros. Es lo que haces con eso lo que cuenta. Intenta encontrar un poco de tiempo cada día, incluso 10 minutos cuando estás en el baño - sí, oíste bien, "en el baño". Multi-tareas en esa situación es posible, pero intentar trabajar mientras miras TV es muy improductivo.

Mejoras en la base de código: Deja la base de código mejor de lo que la encontraste

Muchos repositorios de código (principalmente los de Código Cerrado) van de mal en peor. Por otro lado, los proyectos de Código Abierto tienden a ser todo lo contrario debido a que están en el ojo público. Incluso las mejoras más pequeñas suman y realmente ayudan.

CONSEJO: Ninguna mejora es demasiado pequeña. Hazlo mejor.

Falla rápido con ciclos rápidos de feedback

Los ciclos de feedback incluyen:

  1. Localmente

    • Linters

    • Tests automatizados

  2. Integración Continua (IC)

    • Linters

    • Tests automatizados

    • Deployment con Entrega Continua (EC)

  3. Testeo Manual / Exploratorio

  4. …​

  5. Todo el camino hacia el Cliente y luego el Usuario

Mientras más temprano el feedback y/o cambio, más eficiente será. Por lo tanto, la contracara, mientras más tarde el feedback y/o cambio más costoso será. No sólo porque atravesó más etapas para llegar allí, sino porque luego del cambio, deberá volver a pasar por todo el proceso nuevamente.

Tip
¡Falla rápido!

Accesible

Haga que el proyecto sea Accesible.

Esto tiene 2 áreas:

Baje la barrera para entrar

Permita que todas las personas, jóvenes y personas mayores sean parte de la comunidad y contribuyan.

El producto resultante necesita atender a todos

El acceso para cualquier persona independientemente de su discapacidad (por ejemplo, discapacitados visuales) es fundamental para el éxito de cualquier proyecto.

Por ejemplo:

  • Texto alternativo alt para imágenes

  • Entrada tanto de teclado como de mouse

  • Transcripciones para videos

  • …​

Sugerencia: Sea inclusivo

Etiquetas de GitHub (Labels)

Éstas son realmente útiles por varias razones:

  • Ayudan a la gente a filtrar sus resultados, por ejemplo, por defecto, idea, etc

  • Si las personas quieren contribuir a tu proyecto, una etiqueta que manifiesta help needed (ayuda requerida) va a sobresalir

  • Nivel de dificultad. Los contribuyentes pueden filtrar por el nivel de dificultad en el cual se sienten cómodos

Tip
Pon diferentes etiquetas pero no te vuelvas loco, entre 10-20 está bien

Milestones de GitHub

Usar Milestones (metas) no sólo te da a ti y a tu comunidad visibilidad del objetivo actual y su progreso, sino también de los objetivos futuros y su contenido.

Tip
Alinea tus versiones Release con tus Milestones

Publicaciones / Etiquetas de GitHub

Cuando estés conforme con el trabajo hecho, realiza una Release (publicación) para que tu comunidad sepa que es una versión estable. En las release notes (notas de la publicación), incluye change log (registro de cambios).

Tip
Alinea tus versiones Release con tus Milestones
Relacionado

Ramificaciones

La ramificación es importante cuando se trabaja con un equipo, y aún más importante cuando se trabaja con un equipo más amplio que aún no se conoce.

Proteja su rama principal (generalmente master o develop) y todo debe ir a través de una rama y un Pull Request. Esto debería ser igual para todos, contribuyentes públicos y mantenedores aprobados.

CONSEJO: Existen muchas estrategias de ramificación, un ejemplo es Gitflow, muchas personas usan parte de Gitflow.

Relacionado

Qué No Hacer

Poryecto Big bang

No intentes completar todo el proyecto en un fin de semana maníaco, y luego ignorarlo por el próximo año. Esto no es bueno para tu salud y tampoco habla bien de tu proyecto desde el punto de vista de la comunidad.

Tip
Intenta ser consistente y hacer un poco cada semana. Tus pensamientos e ideas irán mejorando con el tiempo, esto prevendrá que malgastes tu tiempo rehaciendo trabajo cuando tengas un momento de inspiración unos días más tarde.

Commit de dios

Los commits de dios o commits big bang son inútiles y confusos. Son terribles para ti y para la comunidad por demasiadas razones.

Tip
Cada commit debe hacer sólo un ítem

Pull Request de dios

Similar a los "commit de dios", los pull request de dios son una mala idea. Revisar pull request de dios o big bang no sólo es agobiante y laborioso, sino que además dan lugar a revisiones superficiales y por lo tanto errores. Un pull request debe ser una sola característica.

Tip
Nunca nadie se quejó de que un Pull Request era muy pequeño.

Desarrollo guiado por CV

Muchos de nosotros hemos escuchado acerca del Desarrollo guiado por pruebas o Test Driven Development (TDD). No caigas en la trampa del Desarrollo guiado por CV o CV Driven Development (CVDD). Es bueno aumentar tus habilidades con nuevas tecnologías pero haz poco a la vez para reducir el riesgo. No pruebes cada nueva tecnología que deseas aprender en el mismo proyecto, esto es de muy alto riesgo, con la conclusión más probable de un pobre resultado y, por consiguiente, frustración.

Tip
Aproximadamante entre un 10 - 20% de nuevas tecnologías por proyecto es una buena, segura y excitante cantidad.

Dependencia más débil

Tu proyecto es tan bueno como tu dependencia más débil. Revisa las dependencias que incluyes en tu proyecto antes de incluirlas, mira sus:

  • licencia

  • actividad de contribución

  • seguridad

  • colaboradores

Tip
Sé consciente de las dependencias que incluyes. Es estupendo no reinventar la rueda, usualmente hay un montón de opciones disponibles pero asegúrate de realizar tu investigación acerca de las librerías disponibles.

Apéndice

Acronyms

Table 1. Acronyms
Acronym Description Notes

TDD

Test Driven Development

GOOD! Wikipedia

BDD

Behaviour Driven Development

GOOD! Wikipedia

CVDD

CV Driven Development

BAD!

Resources

Tip
Suggestions welcome…​read more at how to contribute
A great way to get involved in open source is to contribute to the existing projects you’re using. GitHub is home to more than 5 million open source projects. There are projects for every skill set like recipes, HTML/CSS, Ruby, Astrophysics and many more. This guide will cover what you might find in a typical project and how to make a great contribution.
— Contributing to Open Source on GitHub
https://guides.github.com/activities/contributing-to-open-source/
Open source works by having many people contribute to the creation and maintenance of software. Thing is, it works well only when people are actually contributing. Successful open source projects thrive on a wide variety of contributions from people with all levels of coding skills and commitment. If just one person fixes a compiler warning, closes a bug, or adds to the documentation, pretty soon you’re talking real progress. For many people, the hardest part is just getting started. So here are some suggested ways you can begin contributing right away, at whatever level is most comfortable for you.
— The Beginner’s Guide to Contributing to Open Source Projects
https://blog.newrelic.com/2014/05/05/open-source_gettingstarted/
GitHub is the home of many popular open source projects like Ruby on Rails, jQuery, Docker, Go and many others. The way people (usually) contribute to an open source project on GitHub is using pull requests. A pull request is basically a patch which includes more information and allows members to discuss it on the website.
— How to contribute to an open source project on GitHub
http://blog.davidecoppola.com/2016/11/howto-contribute-to-open-source-project-on-github/
It’s okay to not know everything, and take one step at a time to learn something new. Don’t waste a lot of time choosing the “right” project. If you know a project or a organization with a beginner-friendly community, just start there. A huge shout-out to all the open source maintainers who have been super responsive and encourage of new contributors. You are helping newcomers navigate huge code bases and contribute in maybe a small yet meaningful ways. Your efforts are truly appreciated and needed.
— A Beginner’s Very Bumpy Journey Through The World of Open Source
https://medium.freecodecamp.com/a-beginners-very-bumpy-journey-through-the-world-of-open-source-4d108d540b39#.an82epenf
You want to focus on the building blocks for your community before you get too deep in the code. "We’ll do it right later" doesn’t always work out well. If you don’t make governance decisions now, things can fall apart, or if you make the wrong decision, it could turn off potential community members going forward.
— How to care for the community over the code
https://opensource.com/article/16/12/community-over-code
For many web developers, accessibility is complex and somewhat difficult. The Accessibility Project understands that and we want to help to make web accessibility easier for front end developers to implement. Blind and visually impaired make up 285,000,000 people according to the World Health Organization (June 2012) with 39,000,000 categorized as legally blind and the remaining 246,000,000 visually impaired. Deaf and hearing impaired make up 275,000,000 (2004) in the moderate-to-profound hearing impairment category.
— Web Accessibility Checklist
http://a11yproject.com/checklist.html

English | Spanish | Filipino
PDF Download
v0.1.17