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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
50caracteres -
No finalices el mensaje con un punto
.. -
Si precisas más de
50caracteres utiliza el cuerpo (descripción) -
Limita el cuerpo a
72caracteres -
Utiliza el cuerpo para explicar
porquénocó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:
-
Localmente
-
Linters
-
Tests automatizados
-
-
Integración Continua (IC)
-
Linters
-
Tests automatizados
-
Deployment con Entrega Continua (EC)
-
-
Testeo Manual / Exploratorio
-
…
-
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.
-
Plantilla de GitHub más información
-
Pruebas automatizadas más información
-
…
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
altpara 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 |
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.
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
| 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.
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.
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.
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.
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.
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.
http://a11yproject.com/checklist.html