Compartir:
){kind=small}
Lorna es ingeniera de software con un incurable hábito bloguero. Intenta domar las palabras y el código a partes iguales.
Uso de las directrices de los repositorios de GitHub para mejorar la experiencia de los desarrolladores
Tiempo de lectura: 3 minutos
En Nexmo, nos encanta compartir código con nuestras comunidades de desarrolladores. Normalmente, esto significa publicar en un repositorio git en GitHub para que cualquier desarrollador que quiera utilizar el código pueda hacerlo.
Sin embargo, nos dimos cuenta de que ahora tenemos alrededor de 300 repositorios entre unas cuantas organizaciones diferentes de GitHub, puede ser complicado encontrar lo que necesitas y también entender cómo utilizar cada proyecto a menos que haya buenas instrucciones.
Para que la experiencia de los desarrolladores sea aún mejor para todos, hemos creado (y luego compartido públicamente) nuestras normas de repositorio.
Reconocimos tres tipos de proyectos que publicamos a menudo y ajustamos nuestras directrices para cada tipo.
Nuestros SDKs son fácilmente los repositorios más utilizados y ¡estamos orgullosos de ellos! Los usuarios de diferentes niveles de experiencia necesitan ser capaces de llegar a estos proyectos y entender cómo pueden utilizarlos en sus propios proyectos para realizar tareas particulares de Nexmo. Hemos tenido especial cuidado con las instrucciones de instalación y dejando claro que la licencia es muy clara para que nuestra comunidad pueda construir sobre nuestros SDKs con confianza.
Publicamos muchas aplicaciones de demostración. Estas son aplicaciones independientes para demostrar una característica particular de Nexmo, y las ponemos a disposición de otros para que las copien y las usen. Tener una declaración clara de las características y el propósito del proyecto es realmente importante en un repositorio como este. También trabajamos en la concesión de licencias y en la inclusión de configuraciones Docker o botones "click to deploy" para permitir a los usuarios probar lo que habíamos hecho para ellos.
El peligro de las normas de cualquier tipo es que se nos escapen de las manos. Muchos de nuestros repositorios no son más que una versión pública de una aplicación independiente que se creó para ilustrar un tutorial, una entrada de blog o un vídeo para mostrar a los desarrolladores algo en particular.
Si sólo publicáramos los que están perfectamente descritos con características de despliegue e instrucciones de uso detalladas, ¡habría muchos menos repositorios en nuestra cuenta de GitHub!
De hecho, la única regla aquí es que el repositorio debe tener un README que incluya un enlace a lo que apoya.
Creamos los Estándares de Repositorio en un intento de capturar una lista compartida de cosas que pensamos que son importantes cuando publicamos un repositorio. Cada uno tenía sus propias ideas, pero al ser un equipo formado principalmente por ingenieros, eso no siempre se traducía en excelencia cuando se trataba de cosas que no son código.
Al crear listas de comprobación y plantillas de las cosas más comunes, convertimos "Haz lo correcto" en "Hacer lo fácil"y mejoramos la experiencia de los desarrolladores a la hora de encontrar nuestros proyectos en GitHub.
Empezamos con una plantilla plantilla README básica para darle una estructura sencilla y recordarnos que debemos enlazar con la documentación para desarrolladores e indicar a los usuarios cómo ponerse en contacto si lo necesitan. Es básico, pero es MUCHO mejor que nada.
Cada repositorio necesita una licencia, y por defecto usamos MIT. Tener las directrices, incluyendo una lista de comprobación, nos recuerda que eso es lo que queremos hacer.
También tenemos un archivo CONTRIBUTING es incompleto porque es difícil de generalizar, pero nos da un punto de partida y deja un poco menos de trabajo a los creadores de repositorios cuando tienen código que compartir.
Los detalles aquí son pequeñas cosas, y hay muchas más cosas en las directrices completas - pero los detalles importan. Los desarrolladores pueden llegar a sus repositorios de GitHub, posiblemente sin saber lo que han encontrado o dónde ir después. Ayudarles a orientarse sobre dónde están, de qué trata este repositorio, y dónde podrían ir a continuación son todos grandes ingredientes para una mejor experiencia del desarrollador.