¿Cómo colaborar con Xamarin.Forms?

Contribuir en Xamarin.Forms

Una de los puntos a favor de Xamarin es su increíble comunidad. Una comunidad activa haciendo constantemente actividades (eventos online, eventos presenciales, etc.) y creando nuevo contenido (artículos, ejemplos, plugins, etc.). Con el paso del tiempo es fantástico ver más y más plugins además de diferentes retos de UI y otro tipo de contenidos que son de ayuda para todos.

Por otro lado, Xamarin.Forms es un proyecto Open Source. Esto tiene una serie de implicaciones entre las que podemos destacar:

  • El código esta disponible. Cualquiera puede revisarlo, compilarlo e incluso aplicar modificaciones.
  • Las issues y PRs son abiertas. De nuevo, cualquiera puede añadir una opinión en una PR o en una futura nueva funcionalidad.
  • Los proyectos de GitHub son públicos. Se puede ver en cada momento en que se esta trabajando, que esta pendiente, etc.
  • La Wiki con aspectos como el Roadmap es público.

Todos los factores anteriores han provocado que cada vez haya un número mayor de colaboraciones de miembros de la comunidad en el repositorio oficial de Xamarin.Forms.

Como miembro del equipo de Xamarin.Forms y habiendo sido colaborador previamente es algo que me encanta ver y fomentar. Por otro lado, recibo en ocasiones correos o mensajes en varios medios (Slack, Skype, etc.) preguntando como puede ayudar a corregir X issue o sencillamente como compilar Xamarin.Forms.

En este artículo, voy a hacer un repaso en las diferentes formas en las que se puede contribuir en Xamarin.Forms, así como compilar el proyecto, poder tomar issues o mejoras, etc.

¿Te interesa?. Vamos a por ello!.

Consejos antes de comenzar

Antes de empezar, colaborar en proyectos Open Source tiene partes positivas como:

  • Es una forma divertida de aprender.

Sin embargo, si nunca has colaborado antes probablemente tengas algunas dudas. La primera de ellas será como hacerlo. Para eso espero que este artículo sea de ayuda. El segundo de los posibles problemas esta en el conocido “síndrome del impostor”. Dudas si lo que haces es correcto,  etc. En este punto, no te preocupes!. Si hay algo que se pueda mejorar, lo verás en el feedback. Es parte de la “gracia” de colaborar así, aprenderás posiblemente cosas nuevas.

Tan solo recuerda:

  • No tengas dudas. Aprenderás cosas nuevas como yo y todos lo hacemos a diario.
  • Puedes preguntar al crear la PR lo que necesites!.

Formas de contribuir

Lo primero de todo, contribuir tiene varias definiciones aunque en este caso:

“se trata de ayudar y concurrir con otros al logro de un cierto fin”

Se puede ayudar de muchas formas!. No tienes porque implementar la espectacular funcionalidad X para poder contribuir.

Vamos a repasar las diferentes opciones disponibles:

  • Reportar una issue.
  • Aportar ideas para nueva funcionalidad.
  • Correcciones en la documentación.
  • Corregir una issue.
  • Nueva funcionalidad.

Reportar una issue

Es una de las formas más sencillas de contribuir. Tienes un problema usando Xamarin.Forms, algo que no se comporta como debería. Abre una issue. De esta forma, avisarás que algo no funciona como debe; se corregirá y en el futuro otros devs tendrán la corrección gracias a que avisaste el problema.

Los pasos a seguir son sencillos:

  1. Logra reproducir un problema de forma constante.
  2. Escribe una Issue explicando el problema. Lo fundamental es detallar en pasos como reproducir el problema.
  3. Detallada cual es el comportamiento que estas obteniendo y cual es el esperado (ayuda a determinar si es una Issue o no).
  4. Añade la versión de Xamarin.Forms utilizada así como la plataforma o plataformas afectadas.
  5. Si es posible, añade algunas capturas.
  6. Si es posible (ayuda muchísimo), añade un pequeño ejemplo adjunto donde reproducir el problema.

Voila!. Sencillo, ¿verdad?.

Recomiendo revisar las issues con el tag excellent-report para ver ejemplos de buenos reportes (buena descripción, pasos, ejemplo adjunto, etc.).

excellent-report

Aportar ideas, añadir nueva funcionalidad

“Estaría genial tener esta propiedad en este control”. Haz una propuesta. Es sencillo, al final es como escribir una issue pero con ligeros cambios.

Los pasos a seguir serían:

  1. Piensa, analiza y piensa de nuevo tu idea.
  2. Abre una issue con el título “[Enhancement] …” y añade una descripción detallada de lo que buscas con esta mejora.
  3. Si has pensado una posible definición para la API añadela.
  4. Si puedes, añade un pequeño ejemplo (Scenario) donde enseñar como se usaría la nueva funcionalidad.
  5. ¿Afecta a alguna API existente?. Indícalo.
  6. Si puedes, añade el nivel de dificultad necesario para implementar la nueva funcionalidad (bajo, medio, alto).
  7. Añade el tag enhancement.

Todo listo!. Puedes ver ejemplos de mejoras buscando en GitHub en las Issues por el tag enhancement. Veamos un ejemplo:

Mejoras

NOTA: Una vez enviada una propuesta, puedes seguir su estado. Revisa el siguiente enlace para conocer los posibles estados (aceptada, rechazada, en progreso, etc.).

Actualizar documentación

¿Encontraste algún error en la documentación?. Puedes enviar también correcciones en la documentación de la Wiki.

Corregir una issue

En este nivel de contribución se ha seleccionado una issue específica a corregir, cuentas con el código fuente sincronizado y ya te dispones a modificar código. Vamos a ver con más detalles este proceso un poco más adelante.

Añadir una nueva funcionalidad

Similar al caso anterior. La diferencia radica que en este caso creas una funcionalidad nueva en lugar de corregir una issue.

Compilar el proyecto

Para compilar el proyecto debemos comenzar por tener el mismo. Es sencillo:

git clone https://github.com/xamarin/Xamarin.Forms.git c:\XamarinForms

Si estas usando Visual Studio para Windows, tras obtener el proyecto no deberás hacer nada especial para compilarlo. Abre la solución Xamarin.Forms.sln y pulsa F5.

Aunque, la solución de Xamarin.Forms tiene varios tipos de proyectos con dependencias del SDK de UWP, .NET Core, etc. Si tienes errores al cargar este tipo de proyectos, primero hay que instalar algunas de las dependencias.

En caso de utilizar Visual Studio para macOS, para evitar problemas de compilación, mi compañero Shane Neuville ha creado un script.

#!/bin/bash

# If you are on Visual Studio for Mac 2017 Turn off automatic package restore before running this script
# If you are on Visual Studio for Mac 2019 you do not need to turn off automatic package restore
# Visual Studio => Preferences => Nuget => General => uncheck the Package Restore box
# Needing to turn restore off isn't necessary in the latest preview releases of VS Mac

# Clean
git clean -dxf

# NuGet restore
msbuild /t:restore Xamarin.forms.sln

# Build XF build tasks
msbuild Xamarin.Forms.Build.Tasks/Xamarin.Forms.Build.Tasks.csproj

# ensure resources are all in sync otherwise first run might cause a Resource ID not found error
msbuild Xamarin.Forms.ControlGallery.Android/Xamarin.Forms.ControlGallery.Android.csproj /t:rebuild

# open in vsmac and should be able to build/run from here
open Xamarin.Forms.sln

NOTA: Visual Studio para macOS soportará MultiTargeting lo que facilitará la compilación de la solución sin script pronto.

Si compilando sigues con problemas, recomiendo:

git clean -xdf

Conociendo el proyecto

La solución de Xamarin.Forms es relativamente grande así que, vamos a ver las claves para que puedas centrar el foco en lo importante.

La solución de Xamarin.Forms

Xamarin.Forms

Cuando se buscan las implementaciones de las abstracciones de controles, bindings , triggers y otro código que no sea específico de plataforma, estos proyectos son la clave.

Xamarin.Forms.Xaml

Extensiones de marcado y otros conceptos clave de XAML lo encontrarás en este proyecto.

Xamarin.Forms.Material

Aquí encontrarás lo necesario relacionado con Visual (de momento Material).

Xamarin.Forms.Maps

Por el nombre probablemente ya sepas que aquí encontrarás a logica del control de mapas.

Platforms

Estos proyectos contienen las implementaciones específicas de cada plataforma. Al agregar nuevos controles o corregir errores relacionados con los controles, aquí es donde efectuará esos cambios.

Control Gallery

Estos proyectos son en realidad una aplicación Xamarin.Forms a modo de galería que incluye todos los controles de Xamarin.Forms disponibles y, lo que es más importante, cuentan con una gran cantidad de UITests de errores previos. Cuando se trabaja en la corrección de un error, o simplemente para investigar cómo se espera que funcione un control, esta aplicación es lo que buscas!.

Xamarin.Forms Control Gallery

Trabajar en una corrección

Ya tienes el proyecto sincronizado y tienes una Issue seleccionada. Ahora si, manos a la obra. Pero antes de comenzar, crea una nueva rama partiendo de lo último disponible en master.

No se requiere cumplir un patrón específico a la hora de crear la rama. Mis recomendaciones serían:

  • Si es un fix, puedes crear una rama “fix{id}” donde el id es el identificador de la Issue.
  • Puedes usar un nombre descriptivo. Por ejemplo, si estas corrigiendo un error al seleccionar un elemento en el ListView podría ser algo como “fix_listview_selectitem”.
  • También puedes usar una combinación de las ideas anteriores. Por ejemplo: “fix_1234_listview_selectitem”.

A la hora de trabajar con el código recuerda cumplir las guías de estilo de código usadas en la .NET Foundation.

Una vez aplicados los cambios necesarios, considera lo siguiente:

  • Si es una corrección, es posible que un test unitario o UITest encaje y ayude a evitar regresiones en el futuro.
  • Si has añadido algo nuevo (por ejemplo, una propiedad nueva al Label), modifica Controls Gallery para reflejar la nueva opción.

El momento de enviar la PR

Añade un título descriptivo junto con una buena descripción (si hay cambios visuales o añadiste algun ejemplo o UITest, añade capturas de pantalla). Si has corregido una issue (o issues) añade el enlace a las mismas.

A continuación, si hay cambios en API añade los detalles. Por último, rellena el checklist indicando si hay UITests, etc.

Enviar PRs

Todo listo para enviar!. Una vez enviado, miembros del equipo así como de la comunidad comenzarán a revisar todo. Una vez pasadas revisiones, builds y otras validaciones. Enhorabuena, tus cambios estarán incluidos en Xamarin.Forms!.

Tras añadir tus cambios en una nueva release, aparecerás nombrado junto a todos los miembros de comunidad que han colaborado al lanzar la versión!.

Gracias

F100s

A la hora de abordar nueva funcionalidad es dificil saber por donde comenzar. Por ese motivo se ha creado la etiqueta F100. Bajo esta etiqueta encontrarás un listado de funcionalidad que cumplen una serie de características:

  • Suele tratarse de funcionalidad no muy amplia y con una buena especificación (explicación detallada, API definida, etc.).
  • El alcance esta bien definido. No hay que modificar o añadir un volumen alto de clases (normalmente).

F100

Si quieres añadir nueva funcionalidad, el listado de F100 es un gran punto de partida!.

Hasta aquí. Creo que hemos realizado un buen resumen de como contribuir en Xamarin.Forms. Además de todo lo expuesto, si puedo ayudar en algo tan solo avísame. Por otro lado, estoy pensando en la idea de hacer algun streaming en Twitch abordando este tema, ¿te resultaría interesante?. Cualquier feedback es bienvenido en los comentarios de la entrada!.

Más información

Anuncios

Un pensamiento en “¿Cómo colaborar con Xamarin.Forms?

  1. This is great and is exactly what I have been looking for in regards to contributing to Xamarin.Forms! I would very much like to see you stream something like how you would go about these steps, for example fixing a reported bug.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google photo

Estás comentando usando tu cuenta de Google. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s