Get best of the week

Guías de código abierto: lanzamiento de un proyecto de código abierto



Prefacio del traductor


Hace un par de meses en Github me topé con el enlace "Guías de código abierto" y no pude salir. En algún lugar de una semana leí cuidadosamente las 10 secciones. Por supuesto, ya sabía sobre el código abierto: leí varios artículos (por ejemplo, "Comprender el código abierto" ), usé tales proyectos en mi trabajo, dirigí preguntas a las comunidades, reporté errores, revisé problemas e incluso hice torpes intentos de luego mejorar, al menos la documentación. Y, por supuesto, estaba en el corazón con estos tipos que comparten software y conocimientos sobre su uso. Sin embargo, el concepto de código abierto era bastante vago y fragmentario. Y este artículo agregó claridad.

Además, tenía un par de proyectos que planeaba lanzar en este formato, con la esperanza del apoyo de la comunidad y con muchos miedos y dudas, y nuevamente este artículo me ayudó a establecer mis intenciones y sugirió pasos prácticos.

Independientemente de su actitud hacia el código abierto, creo que encontrará en esta serie de 10 artículos muchas ideas y hechos interesantes: organizativos, psicológicos, legales, éticos y técnicos.

Dejé que este no programador leyera este texto, dijeron que entendían todo. Y en el título del artículo, deliberadamente puse la "fuente" sin el "código", porque este tema es relevante no solo para los programadores, sino para casi cualquier actividad intelectual en el formato de un proyecto abierto.

Este manual en sí también es de código abierto y ya ha sido traducido a 14 idiomas. Tuve el honor de agregar un hilo ruso y una traducción del primer artículo. Planeo continuar traduciendo artículos por semana. Si alguien quiere conectarse, aquí está el repositorio: Guías de código abierto .

Si de repente alguien necesita un protector de pantalla del encabezado del artículo (ilustraciones + nombres rusos), entonces está en un diseño en codesandbox.io .

Selección de términos


Pido disculpas de antemano por las fallas en la traducción. Algunos términos aparentemente banales no son tan fáciles de aprender en ruso. Por ejemplo, para contribuir, extraer solicitud, emitir, a menudo traducía como "participar en el proyecto, proponer correcciones y una pregunta". Dejé código abierto en inglés hasta ahora. Ya hice un comentario y envié un enlace al diccionario de términos de Github . No me gustó la abundancia de transliteración allí. Si todos estos ishis, pullrequest, push, pool, fork se incluyen en el artículo, entonces será incomprensible para todos los que no trabajaron con Github.

Sí, el problema puede ser una pregunta, una tarea, un informe de error, una oración, etc., y es difícil encontrar una palabra rusa que transmita todos estos significados. Pero el problema de la palabra en inglés tampoco tiene un significado particularmente amplio, solo los creadores y usuarios de Github lo han dotado de tanta amplitud. Si queremos decir con las palabras "abrir una pregunta en Github" que esta pregunta puede ser muy diferente (error, pregunta, solicitud de ayuda, tarea, ...), entonces la palabra "pregunta" reemplazará armoniosamente la palabra "problema". También - push - send, pull - accept, fork - branch, etc. No es la palabra en sí lo que importa, sino el significado que acordamos ponerle. Los británicos, que se encontraron por primera vez con el tema del término en Github, también tienen que leer primero una descripción de todos sus posibles significados dentro del marco de este sistema.Mientras tanto, considero que la claridad es una prioridad para el número máximo de personas que no han trabajado con Github. En cualquier caso, la selección de términos está en el proceso, y la traducción completa, como el original, es de código abierto, por lo que las búsquedas de extracción y abrir con ish.


: ?
«open source»?
?
Open source — ?

open source ?



open source

README






, ( ) !






: ?


Entonces, ¿estás pensando en lanzar tu proyecto de código abierto? ¡Felicidades! El mundo aprecia tu participación. Hablemos sobre qué es el código abierto y por qué la gente lo hace.

¿Qué significa código abierto?


Cuando el código del proyecto está abierto, significa que cualquiera es libre de usar, estudiar, modificar y distribuir su proyecto para cualquier propósito. Estos permisos se otorgan a través de una licencia de código abierto .

La ventaja del código abierto es que reduce las barreras para elegir su programa y colaboración, permitiendo a las personas distribuir y mejorar rápidamente los proyectos. Además, ofrece a los usuarios la capacidad de controlar el código, en lugar de cerrado. Una compañía de software de código abierto (software) puede contratar a alguien para que realice mejoras en el software, en lugar de depender únicamente de la decisión del proveedor de código abierto.

El software libre se refiere a los mismos proyectos quesoftware de código abierto (el código abierto) . A veces puede encontrar combinaciones de estos términos : "Software libre y de código abierto" (software libre y de código abierto FOSS o software libre, libre y de código abierto FLOSS). Las palabras libre y libre aquí significan "gratis", no "gratis" .

¿Por qué la gente abre su trabajo?


avatarUna de las mayores recompensas que he recibido de código abierto es la relación que se ha establecido con otros desarrolladores que enfrentan los mismos problemas que yo.
@ kentcdodds , "Qué bueno fue para mí ingresar al código abierto"

Hay muchas razones por las cuales un individuo u organización abre la fuente de su proyecto. Éstos son algunos de ellos:

  • : Open source . , Exercism, 350 .
  • : Open source , . -. WordPress, , b2.
  • Transparencia: cualquiera puede verificar un proyecto de código abierto en busca de errores e inconsistencias. La transparencia es importante incluso a nivel estatal. Por ejemplo, el gobierno búlgaro y los Estados Unidos legislaron la transparencia para industrias como la banca, la salud y el software de seguridad como Let's Encrypt .

El código abierto es aplicable no solo al software, sino a todo lo demás: desde conjuntos de datos hasta libros. En la revisión de GitHub, puede obtener más ideas sobre lo que puede ser demasiado sensible.

¿El código abierto es gratis?


El código abierto gratuito es uno de sus mayores beneficios, pero no es el único, sino más bien un subproducto de su valor combinado.

Dado que una licencia abierta implica que cualquiera puede usar, modificar y distribuir su proyecto para casi cualquier propósito, en la mayoría de los casos esto implica de forma gratuita. Porque si solicita una tarifa, la gente descargará el proyecto y lo usará de forma gratuita, de forma absolutamente legal.

Por lo tanto, la mayoría de los proyectos de código abierto son gratuitos, pero esto no está incluido en la definición de código abierto. Hay formas de cobrar por proyectos de código abierto indirectamente a través de licencias dobles o características limitadas, pero cumplen con la definición oficial de código abierto.

¿Debo iniciar mi proyecto de código abierto?


La respuesta corta es sí, porque independientemente del resultado, el lanzamiento de su proyecto es una buena manera de entender cómo funciona el código abierto.

Si nunca antes ha ejecutado tales proyectos, puede estar preocupado: "¿qué dirá la gente?", "¿Qué pasa si nadie lo notará en absoluto?" Si esto te resulta familiar, no te preocupes, ¡no eres el único!

El código abierto, como cualquier trabajo creativo, ya sea escribir o dibujar, causa emoción antes de compartirlo con el mundo. Pero la única forma de mejorarlo es practicar, incluso si no tienes una audiencia.

Si aún no lo ha decidido, tómese el tiempo para pensar en sus posibles objetivos.

El establecimiento de metas


Los objetivos lo ayudarán a decidir en qué trabajar, a qué renunciar y dónde necesita ayuda del exterior. Pregúntese: "¿Por qué estoy abriendo este proyecto?" .

No hay una respuesta única para esta pregunta. Puede tener muchos objetivos para un proyecto o diferentes proyectos con objetivos diferentes.

Si su objetivo es simplemente mostrar su trabajo y no hay necesidad de cooperación, puede escribir en el archivo README. Por otro lado, si está interesado en asistentes, debe invertir su tiempo en escribir documentación comprensible y cuidar a los principiantes.
avatar UIAlertView … open source. GitHub. , , . , - . .
mavris@mavris, « : Open Source »

A medida que el proyecto crezca, su comunidad necesitará más que solo código. Respuestas a preguntas (problemas), verificación de código, difusión de información sobre usted: todas estas son tareas importantes de un proyecto de código abierto.

Aunque la cantidad de tiempo dedicado a tareas no programáticas depende del tamaño y la escala de su proyecto, debe estar preparado para resolverlas usted mismo o encontrar un asistente para esto.

Si forma parte de una empresa que lanza un proyecto de código abierto, asegúrese de antemano de que tiene recursos internos para su desarrollo. Asigne un oficial de soporte posterior al lanzamiento y determine cómo se distribuirán las tareas dentro de la comunidad.

Si necesita un presupuesto o personal dedicado para avanzar, operar y apoyar el proyecto, analícelo lo antes posible.
avatarCuando comienza un proyecto de código abierto, es importante que los procesos de gestión en la organización tengan en cuenta la contribución y las capacidades de la comunidad que se ha formado alrededor del proyecto. No tenga miedo de involucrar a personas externas, incluso en aspectos clave, especialmente si están involucrados activamente.
@captainsafia , "Che, ¿quieres abrir el código del proyecto?"

Participación en proyectos ajenos.


Si su objetivo es comprender cómo interactuar con los demás y cómo funciona el código abierto, considere participar en un proyecto existente que utilice y le encante. Su participación puede ser cosas tan simples como errores tipográficos y actualizaciones de documentación.

Si no comprende cómo comenzar a participar en el proyecto de otra persona, consulte nuestra guía Cómo participar en un proyecto de código abierto .

Comenzando su propio proyecto de código abierto


No hay un momento perfecto para abrir la fuente de su trabajo. Puede abrirlos en la etapa de idea, en el proceso de trabajo o después de varios años de cierre.

En general, puede abrir el código fuente cuando se siente lo suficientemente seguro como para mostrar su trabajo a extraños y obtener sus comentarios.

Cada proyecto, independientemente de la etapa en la que decidió abrir la fuente, debe tener la siguiente documentación:


Le ayudarán a transmitir sus expectativas, aceptar los cambios de otros participantes y proteger los derechos legítimos de todos los coautores, incluido usted. Esto aumenta enormemente la probabilidad de una experiencia positiva.

Si su proyecto está en un github y coloca estos archivos en la categoría raíz con los nombres recomendados, el github los reconocerá y los mostrará automáticamente a sus lectores.

Elección de licencia


Una licencia de código abierto asegura que otros puedan usar, copiar, modificar y hacer cambios a su proyecto sin ninguna consecuencia. También lo protege de situaciones legales desagradables. Debe habilitar la licencia al iniciar un proyecto de código abierto.

El trabajo legal no es fácil. Pero hay buenas noticias: puede copiar una licencia existente y colocarla en su repositorio, protegiendo su arduo trabajo en un minuto.

MIT , Apache 2.0 y GPLv3 son las licencias más populares, pero hay otras opciones para elegir.

Cuando crea un nuevo proyecto en Github, puede elegir entre varias licencias. Al elegir una licencia de código abierto, abrirá su proyecto.

Elige una licencia

Si tiene otras preguntas o inquietudes con respecto a los aspectos legales del código abierto, las describimos aquí .

Recopilación de README


El archivo README ("léame") no solo explica cómo usar su proyecto, sino que también explica por qué es importante y qué pueden hacer los usuarios con él.

Intenta responder las siguientes preguntas en README:

  • ¿Qué hace este proyecto?
  • ¿Cómo es útil este proyecto?
  • ¿Cómo puedo comenzar a trabajar con él?
  • ¿Dónde puedo obtener ayuda si es necesario?

Puede especificar en README: cómo participar en su proyecto, cuáles son sus objetivos, hablar sobre la licencia y la autoría. Si no planea aceptar las mejoras de otras personas, o si él todavía no está listo para correr, simplemente escriba sobre eso.
avatarUna buena documentación significa más usuarios, menos solicitudes de ayuda y más colaboradores. (...) Recuerde que sus usuarios no son usted. Estas pueden ser personas con experiencia, muy diferentes a las suyas.
@tracymakes , "Escribe para que se lean tus palabras (video)"

A veces las personas posponen escribir README porque sienten que el proyecto no está terminado o no quieren aceptar las mejoras de otras personas. Pero esta es solo una buena razón para escribir al respecto.

Para inspirarte, puedes leer la guía "Make README" o la Plantilla README .

Cuando agrega el archivo README al directorio raíz del proyecto, el github lo muestra automáticamente en la página principal del repositorio.

Escribir una guía para los participantes.


El archivo CONTRIBUYENTE le dice a su audiencia cómo convertirse en miembro de su proyecto. Por ejemplo:


Además de los detalles técnicos, el archivo CONTRIBUYENTE es un buen lugar para expresar sus expectativas con respecto a la participación de otras personas. Por ejemplo:

  • ¿Qué tipo de participación estás esperando?
  • Sus planes y visión para el desarrollo del proyecto.
  • Cómo los participantes pueden (y no pueden) contactarlo

Su tono cálido y amigable y sus propuestas específicas de participación, como escribir documentación o crear un sitio, pueden ser de gran importancia para atraer a los recién llegados a trabajar en un proyecto.

Por ejemplo, Active Admin comienza su guía de participación con estas palabras:
En primer lugar, queremos agradecerle por considerar participar en el desarrollo de Active Admin. Son las personas como usted las que hacen de Active Admin una gran herramienta.

En las primeras etapas de un proyecto, su archivo CONTRIBUYENTE puede ser simple. Siempre debe explicar cómo informar errores y completar preguntas, así como describir los requisitos técnicos para editar miembros (por ejemplo, pruebas).

Con el tiempo, puede complementarlo con respuestas a preguntas frecuentes. Debido a esto, menos personas le preguntarán lo mismo una y otra vez.

Para facilitar la compilación de un archivo CONTRIBUYENTE, consulte la plantilla de guía de colaboración de @ nayafia omozilla's "Cómo compilar el archivo CONTRIBUTING.md" .

Enlace al archivo CONTRIBUYENTE dentro del archivo README, para que más personas lo vean. Si coloca el archivo CONTRIBUTING.md en la raíz de su proyecto , el github lo consultará automáticamente cuando alguien abra una nueva pregunta (problema) o agregue una edición al proyecto (solicitud de extracción).

guía de colaboración

Desarrollo de un código de conducta.


avatarTodos enfrentamos situaciones desagradables cuando el propietario del proyecto explicó groseramente algo o los usuarios hicieron preguntas básicas. (...) Un código de conducta se convierte en un documento que es fácil de consultar y que dice que su equipo toma muy en serio un diálogo constructivo.
@mlynch , haciendo del código abierto un lugar más feliz

Como resultado, el código de conducta establece las reglas básicas de conducta para los participantes en su proyecto. Esto es especialmente importante si está lanzando un proyecto para una empresa o comunidad. Un código de conducta ayuda a establecer un comportamiento saludable y constructivo en la comunidad, lo que reduce el estrés para usted como la persona responsable del proyecto.

Ver más detalles: Código de conducta - Guía .

Además de describir cómo desea que se comporten los participantes, el código de conducta también explica a quién y cuándo se aplica, y qué sucederá si se viola.

Por analogía con la licencia, no tiene que escribir el código usted mismo, pero puede copiar una de las opciones existentes. El acuerdo de miembro se utiliza enMás de 40,000 proyectos de código abierto, incluidos Kubernetes, Rails y Swift. Independientemente del código que utilice, debe estar preparado para aplicarlo si es necesario.

Coloque el archivo CODE_OF_CONDUCT.md en la raíz de su proyecto, para que sea más fácil encontrarlo y vincularlo, por ejemplo, desde README.

Nombrando y marcando su proyecto


La marca no solo es un logotipo pegadizo y un nombre memorable, sino también cómo habla sobre su proyecto y a quién llega su mensaje.

Elegir el nombre correcto


Elija un nombre que sea fácil de recordar e, idealmente, dé una idea de la esencia del proyecto. Por ejemplo:


Si su proyecto es una adición a un proyecto existente, use su nombre como prefijo, esto ayudará a comprender lo que está haciendo su proyecto. Por ejemplo, node-fetch trae `window.fetch` a Node.js).

Opta por la claridad. Los juegos de palabras pueden ser divertidos, pero piensa en personas de otras culturas o con experiencias diferentes a las tuyas que podrían no entender el chiste. Sus usuarios potenciales pueden ser empleados de empresas que hablarán con sus superiores sobre su proyecto. No los haga sonrojar al mismo tiempo.

Conflicto de nombre


Busque proyectos de código abierto con el mismo nombre , especialmente si usa el mismo idioma o ecosistema. Si su nombre coincide con un proyecto popular existente, puede confundir a su audiencia.

Si planea iniciar un sitio web, Twitter o cualquier plataforma de publicación, asegúrese de que el nombre que necesita esté libre allí. Y es mejor reservar estos nombres ahora para su tranquilidad, incluso si aún no planea usarlos.

Asegúrese de no infringir la marca registrada de ninguna compañía. En el futuro, ella podrá pedirle que cierre el proyecto o incluso demandarlo. Este es un riesgo injustificado.

Puede consultar el conflicto de la marca en la base de datos global de marcas de la OMPI. Si está realizando el proyecto en nombre de la empresa, el departamento legal puede ayudarlo con esto .

Finalmente, haga una búsqueda rápida en Google sobre el nombre de su proyecto. ¿Las personas podrán encontrar fácilmente su proyecto en él? ¿O tal vez algo indeseable aparece en esta solicitud?

¡La forma en que escribe (y codifica) también afecta a su marca!


A lo largo de la vida del proyecto, escribirás mucho: README, guías, documentos de la comunidad, respuestas a preguntas, tal vez incluso boletines y listas de correo.

Ya sea documentación oficial o un mensaje regular, su estilo de escritura es parte de la marca del proyecto. Piensa en la luz con la que miras delante de la audiencia y si has elegido el tono correcto.
avatar , , . , , , , .
@janl, CouchDB, « Open Source»

Un lenguaje amable y cortés creará un ambiente agradable para los nuevos participantes. Además, vigile la simplicidad de la presentación, ya que para muchos lectores el inglés puede no ser nativo.

No solo las palabras que escribe, sino también el estilo del código pueden formar parte de la marca de su proyecto. Angular y jQuery son dos proyectos de muestra con estilos y recomendaciones rigurosos.

No es necesario escribir una guía de estilo cuando recién está comenzando y, en cualquier caso, es probable que desee incluir diferentes estilos en su proyecto. Pero debe comprender de antemano que su estilo de escritura y código atraerá a algunas personas y alejará a otras. Las primeras etapas del proyecto son una oportunidad para crear un precedente a partir del cual el proyecto crecerá en la forma que desee.

Lista de verificación antes de comenzar


¿Estás listo para abrir tu proyecto? Aquí hay una lista de verificación para ayudarlo. Cuando haya marcado todos los elementos, haga clic en "publicar" y felicítese.

Documentación


  • Hay un archivo de LICENCIA de código abierto en el proyecto
  • El proyecto tiene documentación básica (README, CONTRIBUTING, CODE_OF_CONDUCT)
  • El nombre es fácil de recordar, da una idea de la esencia del proyecto, no entra en conflicto con los proyectos existentes y no invade las marcas registradas.
  • La lista de problemas está actualizada, bien organizada y etiquetada.

El código


  • El proyecto utiliza convenios de código acordados y nombres descriptivos de funciones / métodos / variables
  • El código se comenta claramente, se documentan intenciones y casos especiales.
  • En ninguna parte hay datos confidenciales, como contraseñas u otra información no pública, en el historial de revisiones, problemas (problemas) y solicitudes de revisiones (solicitudes de extracción).

Personas


Si eres un particular:

  • Hablaste con el departamento legal y / o entendiste las reglas de propiedad intelectual de tu empresa y las políticas de código abierto (si estás empleado en algún lugar)

Si eres una entidad legal:

  • Hablaste con el departamento legal
  • ¿Tiene un plan de marketing para lanzar y promover un proyecto?
  • Alguien ha sido designado responsable de interactuar con la comunidad: responder preguntas, verificar solicitudes de extracción y adjuntarlas al proyecto
  • Al menos dos personas tienen acceso administrativo al proyecto.

¡Lo hiciste!


¡Felicitaciones por abrir el código fuente para su primer proyecto! Independientemente del resultado, trabajar a la vista de las personas es un regalo para la comunidad. Cada solicitud de compromiso, comentario y revisión es una oportunidad para aprender y crecer para usted y para otros.

More articles:


All Articles