Proceso de Informe de Estado de FreeBSD

No asumas que la persona que lee el informe sabe acerca de tu proyecto.

Los informes de estado se distribuyen ampliamente. Están habitualmente en lo alto de la lista de noticias en el sitio web de FreeBSD y son una de las primeras cosas que la gente leerá si quieren conocer lo que es FreeBSD. Considera este ejemplo:

Alguien que lea esto, si está familiarizado con las páginas de manual de UNIX, sabrá que acb(4) es algún tipo de dispositivo. ¿Pero por qué le debería importar al lector?¿Qué tipo de dispositivo es? Compara con esta versión:

Ahora el lector sabe que abc es un controlador de un interfaz de red. Incluso si no usa ninguno de los productos de Yoyodyne, has comunicado que el soporte en FreeBSD para los dispositivos de red está mejorando.

Los informes de estado no son sólo para decirle a todo el mundo que se están haciendo cosas, también necesitan explicar por qué se están haciendo.

Continuemos con el ejemplo anterior. ¿Por qué es interesante que ahora soportemos las tarjetas Frobnicator de Yoyodyne? ¿Son habituales? ¿Se usan en algún dispositivo popular? ¿Se usan en un nicho de mercado particular donde FreeBSD tiene (o le gustaría tener) presencia? ¿Son las tarjetas más rápidas del planeta? Los informes de error habitualmente incluyen cosas como estas:

Y luego paran. A lo mejor el lector es un ávido fan de Cyberdyne y conoce todas las características excitantes del nuevo T800. Es improbable. Es mucho más probable que haya oído hablar vagamente de lo que quiera que hayas importado (especialmente en el árbol de ports: recuerda que hay cerca de 30,000 cosas ahí también…​). Proporciona una lista de nuevas características, o fallos corregidos. Diles por qué es bueno que tengamos una nueva versión.

No recicles los mismos elementos del informe de estado.

Ten en cuenta que los informes de estado no son sólo informes de estado del proyecto, son informes sobre el cambio de estado del proyecto. Si hay un proyecto en curso, utiliza un par de frases para presentarlo, pero utiliza el resto del informe hablando acerca del trabajo nuevo ¿Qué progresos se han hecho desde el último informe? ¿Qué queda por hacer? ¿Cuándo es probable que termine (o, si "terminado" no se puede aplicar, cuando está previsto que esté listo para un uso más amplio, para pruebas, para desplegarlo en producción, etc)?

No te olvides de tus patrocinadores.

Si tú o tu proyecto habéis recibido patrocinio, una beca de alguien o habéis trabajado como consultor externo o empleado para una empresa, por favor inclúyelo. Los patrocinadores siempre aprecian que les agradezcas su inversión, pero también es beneficioso para ellos mostrar que están activos apoyando el Proyecto de esta forma. Por último, pero no por ello menos importante, esto ayuda a FreeBSD a aprender más acerca de sus consumidores importantes.

Si se necesita ayuda, ¡hazlo explícito!

¿Se necesita ayuda con algo? ¿Hay tareas que pueda hacer otra gente? Hay dos formas en la que puedes usar la parte de elementos abiertos del informe de estado: para solicitar ayuda, o para ofrecer un resumen rápido de la cantidad de trabajo pendiente. Si ya hay suficiente gente trabajando en el proyecto, o si está en un estado en el que añadir más gente no va a hacer que vaya más rápido, entonces esta segunda opción es mejor. Da algunos elementos grandes que están en progreso, y quizás indica quién se está enfocando en cada uno.

Lista tareas, con suficiente detalle como para que la gente sepa si son capaces de hacerlas, e invita a que la gente entre en contacto.

Los siguientes métodos están disponibles para enviar tus informes:

Está disponible una plantilla de ejemplo en formato Asciidoc.

Los informes siempre son aceptado por el status team, pero el proceso de recolección principal sucede en el último mes de cada trimestre, esto es en Marzo, Junio, Septiembre y Diciembre. Se enviarán llamadas para los informes de estado en esos meses. Los meses de Enero, Abril, Julio y Octubre se dedican a organizar los informes enviados durante el trimestre anterior; esto puede incluir esperar por envíos tardíos. La publicación de los informes de estado se realiza durante los mismos meses en cuanto el informe está listo.

Todos los envíos de informes pueden extender su fecha límite enviando un email al status team hasta la fecha extendida, que es 8 días después del final del trimestre. Las entradas del equipo de gestión de ports tienen por defecto la fecha de entrega extendida, porque los informes de estado se solapan con las ramas trimestrales de los ports.

La revisión de los informes enviados por parte de gente que no es parte del status team debería estar completada a mediados de Enero/Abril/Julio/Octubre (congelación de la revisión de terceros). Es decir, con excepción de faltas ortográficas u otro tipo de edición sencilla, el status team debería empezar a ensamblar los envíos poco después del día 15. Fíjate en que no es un congelación completa, y el status team todavía podría aceptar revisiones por entonces.

Las llamadas para los informes de estado se envían a los siguientes destinatarios:

La forma más fácil de enviar las llamadas para los informes de estado es usar el script perl sendcalls en el directorio tools/sendcalls del repositorio doc en git . El script automáticamente envía llamadas a todos los destinatarios. También puede ser usado desde un trabajo cron, por ejemplo:

También podría merecer la pena hacer una llamada para los informes en los foros como se hizo en el pasado.

Los informes enviados son revisados e integrados en el subdirectorio apropiado de doc/website/content/en/status/ conforme van llegado. Mientras los informes están siendo actualizados, gente fuera del status team también puede revisar las entradas individuales y proponer arreglos.

Normalmente el último paso en el proceso de revisión del contenido es escribir la introducción en un fichero llamado intro.adoc: una buena introducción sólo puede escribirse una vez que se han recolectado todos los informes. Si es posible, es una buena idea pedir a distintas personas que escriban la introducción para añadir variedad: personas distintas ofrecerán distintos puntos de vista y ayudarán a mantenerlo fresco.

Una vez que los informes y la introducción están listos, se necesita crear el fichero _index.adoc: este es el fichero en el que los informes son distribuidos en categorías y ordenados.

Cuando todos los ficheros del informe de estado están listos, es momento de publicarlo.

Primero se edita doc/website/content/en/status/index.adoc: se actualiza la siguiente fecha de entra y se añade un enlace al nuevo informe. Después se empuja el cambio al repositorio y el _status team comprueba que todo funciona como se espera.

Después se añade la entrada a la sección de noticias de la página web principal en doc/website/data/en/news/news.toml.

Aquí hay una muestra de la entrada de noticias:

Una vez que la versión HTML del informe se ha construido y está online, se usa w3m(1) para volcar la página web como texto plano, e.g:

w3m(1) tiene soporte completo para unicod. -dump simplemente extrae texto renderizado del código HTML en el que se pueden omitir algunos elementos, mientras que -cols asegura que todo está dentro del límite de 80 columnas.

Se añade un enlace al informe renderizado entre la introducción y la primera entrada.

Finalmente el informe está listo para ser enviado, cambiando la disposición (el informe debe ser inline), y asegurándose de que esté codificado en UTF-8.

Se envían dos correos, ambos con un tema con formato FreeBSD Status Report - <First/Second/Third/Fourth> Quarter <year>: