Colaboración para el desarrollo y buenas prácticas
Trabajando con un gran número de equipos de desarrollo en muchos proyectos y organizaciones, descubrimos que es útil recopilar algunas de nuestras perspectivas. Algunos de ellos están relacionados con AEM, pero la mayoría están relacionados con el desarrollo de front-end de uso general o son solo directrices generales sobre cómo colaborar en un equipo de desarrolladores.
Puede leer algunos de estos elementos y pensar que, en general, se entiende como sentido común entre los desarrolladores. Estamos de acuerdo y es una buena señal de que está listo para trabajar de forma colaborativa en proyectos de AEM junto con otros desarrolladores.
En este punto, esto es solo una colección de lecciones aprendidas de nuestras participaciones en un creciente conjunto de proyectos.
GitHub
Crear solicitudes de extracción
Si trabaja en un proyecto con varios desarrolladores, no suele ser aconsejable insertar directamente en main. Cuando el proyecto se encuentra en producción, los cambios en el código que se combinan o insertan en main suelen significar que se liberan en producción. La protección de la rama main es un buen mecanismo para garantizar que las personas no inserten main por accidente, lo cual es especialmente aconsejable con un sitio que esté en producción. Mantenga el ámbito de la solicitud de extracción según lo que aparece en el título/descripción de la PR.
Etiqueta de solicitud de extracción
Si abre una solicitud de extracción, asegúrese de incluir una dirección URL a una página (o varios vínculos a páginas) de la rama para que el revisor pueda ver el código en acción. Si va a actualizar el código de un bloque existente, asegúrese de incluir el vínculo que incluye el bloque que está actualizando, ya que es posible que el revisor no sepa dónde se utiliza este bloque para probar su funcionalidad.
Bot de AEM Github
El bot de AEM Github y la configuración estándar del proyecto de plantillas comprobarán la vinculación de sus perspectivas CSS/JS y PageSpeed para el rendimiento web, la accesibilidad, la SEO y las prácticas recomendadas. No envíe una solicitud de extracción para revisión que tenga errores de enlace o que no tenga una puntuación de Lighthouse de Page Speed Insights de 100.
Repasos
Se recomienda que el mantenedor o el desarrollador principal del proyecto en el que está trabajando revise su código. Para que el revisor vea una puntuación de rendimiento de PageSpeedInsight realista, incluya vínculos al entorno .live en caché.
Si usted es el mantenedor o el desarrollador principal de un proyecto que no está en producción y está agregando código o cambiando su propio código, a veces la sobrecarga es innecesaria para que sus PR sean revisadas por los compañeros y a menudo es aceptable fusionar sus propias PR sin una revisión por pares.
Combinación de solicitudes de extracción
Combine solo sus propias solicitudes de extracción. Si la persona que abrió la solicitud de extracción tiene la capacidad de combinar su propia solicitud de extracción, el autor del código es la persona ideal para combinar. Hay situaciones en las que el autor afirma específicamente que esto puede y debe ser fusionado por otra persona, y en esos casos un mantenedor (desarrollador principal) del proyecto debe sentirse libre de fusionar una solicitud de extracción.
Incluso si se aprueba una solicitud de extracción, siempre debe consultar al autor de la solicitud de extracción si están listas para fusionarse.
Para el trabajo que aún se está realizando, abrir una solicitud de extracción de borrador también contribuye a evitar una combinación accidental.
Ramas compartidas
Se recomienda considerar las ramas para solicitudes de extracción individuales como inicialmente una ubicación privada del desarrollador que creó la rama. No se limite a insertar en las ramas de otros desarrolladores sin haber sido invitado a hacerlo. Hay situaciones en las que las personas colaboran en solicitudes de extracción, pero debe ser un acuerdo explícito.
Desarrollo (a escala) basado en troncos
AEM funciona muy bien en un desarrollo a escala basado en tronco con desarrolladores integrados y CI/CD. Esto significa que puede combinar un gran número de solicitudes de extracción pequeñas en principal (producción), pero los esfuerzos de Assurance de calidad/revisión se pueden adaptar al impacto de un pequeño cambio. Nadie quiere revisar y probar grandes solicitudes de extracción, y las ramas de larga duración con muchos cambios tienden a ser difíciles (y peligrosas) de fusionar.
Linting
No cambie las configuraciones de linting (eslint airbnb-base y stylelint) a menos que tenga una buena razón. La preferencia personal no es una buena razón. Cambiar la vinculación hace que sea muy difícil mover desarrolladores de un proyecto a otro. Argumentar si algo es una buena razón para cambiar la configuración de la vinculación suele ser mucho más arduo que simplemente decir categóricamente que no.
CSS
Aislamiento del bloque selector de CSS
Los bloques de AEM suelen funcionar como componentes de forma colaborativa en el mismo DOM/CSSOM. Esto significa que debe escribir los selectores de CSS en un bloque .css de forma que se aísle el CSS de afectar al diseño de los elementos fuera del bloque. La forma más sencilla de hacerlo es asegurarse de que todos los selectores CSS de .css de un bloque solo se apliquen al bloque.
Cascada en CSS
Utilice sus nombres de clase CSS con prudencia. Algunas clases y variables CSS se utilizan en diferentes bloques y no se espera que otras se utilicen fuera del bloque. Se recomienda utilizar como prefijo clases y variables que son privadas para el bloque con el nombre del bloque. Por el contrario, si hay clases CSS y un contexto CSS que se deban heredar (a menudo, estos se pueden crear), esas clases y variables no deben tener un prefijo.
Sangría CSS y orden de propiedad
Fuera de una PR de refactorización CSS, no cambie la secuenciación en las propiedades o la sangría en los archivos CSS que toque en una PR funcional. Cada desarrollador tiene diferentes preferencias en el orden de clasificación de las propiedades o la sangría. Asegúrese de que la diferencia que ve en su PR esté aislada de los cambios que realmente desea que se revisen antes de enviarla.
Complejidad de selectores CSS
No deje que los selectores CSS se vuelvan complejos e ilegibles. A menudo, es mejor decorar clases o elementos CSS adicionales en su DOM y escribir CSS legible en su lugar. Los selectores CSS complejos también suelen ser más difíciles de mantener y más flexibles que los equivalentes en JS.
Nomenclatura CSS
Nombrar las clases de forma sencilla e intuitiva resulta útil para otros desarrolladores. Evite el espacio de nombres a menos que sea necesario dentro del ámbito de un proyecto. A menudo no hay necesidad de especificar el tipo o el origen (p. ej. nombre del sistema de diseño) de una variable CSS que se va a utilizar en todo el proyecto.
Aproveche los Atributos de ARIA para el estilo
En muchas situaciones, agregará atributos ARIA para la accesibilidad. Dado que tienen una semántica bien definida como expanded o hidden que todos los desarrolladores entienden, en la mayoría de los casos no es necesario que se incluyan clases adicionales en el vocabulario que tengan una semántica desconocida.
Móvil primero
Por lo general, los proyectos web deben desarrollarse "primero móvil". Esto significa que el CSS sin consulta de medios debe representar un sitio móvil. Añada consultas de medios para ampliar el diseño para tabletas y equipos de escritorio.
Puntos de interrupción
En general, use 600px, 900px y 1200px como puntos de interrupción, todos min-width. No mezcle min-width y max-width. Utilice únicamente puntos de interrupción diferentes en casos excepcionales en los que entienda bien por qué es necesario.
Menos, Sass, PostCSS, Tailwind y amigos.
Si está trabajando en el contexto de una organización más grande, asegúrese de no introducir una dependencia a ningún preprocesador CSS o marco de trabajo de su preferencia personal sin obtener la aprobación de todo el equipo y la organización. Dado que existen muchas preferencias personales diferentes en esta área, es difícil mantener el código si cada proyecto o cada bloque dentro de un proyecto utiliza tecnologías diferentes.
La solución más sencilla es confiar en el creciente restablecimiento de funciones CSS que admiten los exploradores.
Funciones modernas de CSS
Asegúrese de que las funciones que utiliza sean compatibles con los exploradores evergreen. Dependiendo de las características, puede aceptarse una compatibilidad más o menos generalizada.
JavaScript
Marcos
En la mayoría de los sitios web, los marcos de trabajo son excesivos para problemas de diseño simples fuera de la funcionalidad de aplicación. Los marcos suelen introducir problemas de rendimiento web (elementos vitales de Lighthouse y Core Web), especialmente si se encuentran en la ruta de LCP o introducen TBT, al tiempo que intentan abordar problemas triviales. Mantenga las cosas simples simples.
Si utiliza marcos de JavaScript, asegúrese de no introducir una dependencia de ningún marco de JS o biblioteca de su preferencia personal sin obtener la aprobación de todo el equipo y la organización. Dado que hay muchas preferencias personales, es difícil mantener el código si cada proyecto o cada bloque dentro de un proyecto utiliza tecnologías diferentes.
La solución más sencilla es confiar en el creciente restablecimiento de funciones compatible con los exploradores.
Generar cadena de herramientas
Las diferentes cadenas de herramientas de compilación de un proyecto a otro dificultan la incorporación de nuevos desarrolladores y a menudo añaden complejidad adicional. Asegúrese de no introducir una dependencia de sus preferencias personales sin obtener la aprobación de todo el equipo y la organización.
La solución más sencilla es mantener todo el proyecto sin compilaciones.
Funciones modernas de JavaScript
Asegúrese de que las funciones que utiliza sean compatibles con los exploradores evergreen. Dependiendo de las características, puede aceptarse una compatibilidad más o menos generalizada. Aunque AEM se puede usar con cualquier explorador, lib-franklin.js depende de exploradores que admitan import() dinámico. Cualquier característica compatible con el conjunto de exploradores que admiten import() dinámico debe considerarse segura. Técnicamente, por supuesto, los navegadores más antiguos (p. ej. IE) pueden ser compatibles con los proyectos de AEM, pero requieren una gran personalización.
No todas las funciones tienen las mismas consecuencias si un explorador no las admite, algunas pueden ser estéticas y otras pueden impedir que el sitio funcione. Un ejemplo común es "encadenamiento opcional". Si un explorador no admite el "encadenamiento opcional", un solo uso puede tener consecuencias fatales para toda la página.
Carga de bibliotecas de terceros
No agregue bibliotecas de terceros a <head> a través de head.html, ya que se encontrarán en la ruta crítica de carga de contenido sobre el pliegue y, a menudo, se cargarán cuando no sean necesarias. Agregue las dependencias donde sea necesario mediante loadScript() al bloque específico que tenga el requisito correspondiente.
En el caso de bibliotecas de terceros más grandes, le recomendamos considerar el uso de un IntersectionObserver para asegurarse de que solo las carga cuando el bloque, en función de él, se esté desplazando a la vista.
Biblioteca AEM (aem.js)
La biblioteca de AEM (generalmente alojada en aem.js en un proyecto) no está minificada ni ofuscada para facilitar la depuración. No recomendamos realizar cambios en él sobre la base de un proyecto y, en su lugar, recomendamos extensiones específicas de proyecto que se mantengan fuera de la biblioteca. Agradecemos las solicitudes de extracción a través de github, si desea proponer cambios o correcciones de errores que sean universalmente aplicables.
<head>
El <head> que se entrega desde el servidor como parte del marcado de HTML debe permanecer mínimo y sin tecnología de marketing como Adobe Web SDK, Google Tag Manager u otros scripts de terceros debido a impactos en el rendimiento. Tampoco se recomienda agregar scripts o estilos en línea a <head> por motivos de rendimiento y administración de código.
Minificación
Normalmente, esto es una complejidad adicional sin muchos beneficios a menos que tenga archivos JS/CSS realmente grandes, que de nuevo sería un antipatrón. Con Edge Delivery, la forma en que el código está estructurado en torno a bloques, los archivos deben ser generalmente de pequeño tamaño y la minificación no debe marcar una gran diferencia. Sin duda, puede comparar LHS minificación previa/posterior.
La minificación hace que el código sea ligeramente más difícil de depurar y se necesitan mapas de código fuente. Además, la minificación requiere un paso de compilación adicional que puede ralentizar potencialmente el trabajo de desarrollo del sitio. Por lo tanto, es recomendable ir allí solo si existe un beneficio tangible de esta complejidad adicional
Contenido en Sharepoint/Google Drive
Inicie su desarrollo con contenido
Antes de escribir una línea de código, cree el contenido (de ejemplo) en un documento de Word o Google (o en una hoja de cálculo). Asegúrese de que se siente bien para la creación y compártala con personas de su equipo que tengan experiencia apoyando a los autores. Requiere experiencia de soporte para comprender qué estructuras de contenido son fáciles de comprender y recrear para los autores. Una vez que se haya asentado en una estructura de contenido que contiene todos los elementos que necesita para su bloque y lo haya revisado, puede empezar a desarrollar su código CSS y JS.
Uso /drafts
El ciclo de vida del contenido es muy diferente del ciclo de vida del código. Si va a proponer cambios en una estructura de contenido existente de su código o crea un bloque nuevo, no se limite a realizar esos cambios en la página en la que está trabajando. Copie la página en la carpeta /drafts/<yourname>/ y realice los cambios allí.
Una vez que los cambios del código se hayan combinado con main , puede hacer que los autores copien o combinen el contenido con el contenido fuera de la carpeta /drafts/.
Compatibilidad con versiones anteriores de las nuevas funciones
Especialmente en entornos de producción, es importante mantener los cambios anticipados en la estructura de contenido compatible con el contenido existente. Lo ideal es que el código que se combina no tenga impacto en el sitio web ni requiera la refactorización del contenido. Solo cuando se coloca nuevo contenido a través de un ciclo de vista previa y publicación, la nueva funcionalidad está disponible. Por supuesto, esto no se aplica a cosas como cambios de diseño en el contenido existente o correcciones de errores funcionales.
Uso del contenido para recursos "estáticos"
Por lo general, no es aconsejable utilizar binarios en el repositorio de GitHub. Incluso los recursos estáticos basados en texto, como archivos HTML o SVG, solo deben colocarse en GitHub en casos excepcionales. Una buena razón para agregar una SVG a su repositorio de Git es si se hace referencia a ella desde el código. No comprometa nada que esté relacionado con el proceso de creación de contenido o que pueda formar parte de un proceso de creación. Hay algunas excepciones (generalmente relacionadas con clientes heredados y que no son de explorador) que requieren un determinado conjunto de recursos fijos que AEM no puede producir y manipular dinámicamente, pero que, en general, se producen si encuentra un gran conjunto de recursos estáticos (p. ej., imágenes, etc.) o un archivo HTML en una PR, probablemente no sea una buena práctica.
Usar contenido para cadenas/literales
Las cadenas que se muestran a los usuarios finales y que podrían traducirse o cambiarse en algún momento siempre deben poder crearse y proceder de contenido (p. ej., placeholders u otras hojas de cálculo o documentos). Si tiene una cadena literal que se muestra como texto al visitante de su sitio web en su código javascript o css, se recomienda reemplazarla con una referencia al contenido (p. ej. placeholders).