Collaboration de desenvolvimento e práticas recomendadas

Trabalhando com um grande número de equipes de desenvolvimento em vários projetos e organizações, descobrimos que é útil coletar alguns de nossos insights. Alguns deles estão relacionados ao AEM, mas a maioria está relacionada ao desenvolvimento de front-end de uso geral ou são apenas diretrizes gerais sobre como colaborar em uma equipe de desenvolvedores.

Você pode ler alguns desses itens e pensar que isso é geralmente entendido como senso comum entre os desenvolvedores. Concordamos, e isso é um ótimo sinal de que você está pronto para trabalhar de forma colaborativa em projetos do AEM, juntamente com outros desenvolvedores.

Neste ponto, trata-se apenas de uma coleção de lições aprendidas com nossos envolvimentos em um conjunto crescente de projetos.

GitHub

Criar Solicitações Pull

Se você trabalhar em um projeto com vários desenvolvedores, raramente é uma boa ideia enviar diretamente para main. Quando seu projeto está em produção, as alterações de código mescladas ou enviadas por push para main geralmente significam que elas foram liberadas para produção. Proteger sua ramificação main é um bom mecanismo para garantir que as pessoas não enviem para main por acidente, o que é especialmente aconselhável em um site que esteja em produção. Mantenha o escopo de sua solicitação de pull conforme o título/descrição da PR.

Etiqueta de solicitação de pull

Se você abrir uma solicitação de pull, certifique-se de incluir um URL para uma página (ou um número de links para páginas) na ramificação, onde o revisor possa ver seu código em ação. Se estiver atualizando o código de um bloco existente, certifique-se de incluir o link que apresenta o bloco que você está atualizando, pois o revisor pode não saber onde esse bloco está em uso para testar sua funcionalidade.

AEM Github Bot

O AEM Github Bot e a configuração padrão do projeto Boilerplate verificarão a listagem do CSS/JS e dos insights do PageSpeed para desempenho da Web, acessibilidade, SEO e práticas recomendadas. Não envie uma Solicitação de pull para revisão que tenha erros de listagem ou que não tenha uma Pontuação de farol do Page Speed Insights de 100.

Revisões

É uma boa prática ter seu código revisado pelo mantenedor ou desenvolvedor principal do projeto em que você está trabalhando. Para que o revisor veja uma pontuação realista de desempenho de PageSpeedInsight, inclua links para o ambiente .live em cache.
Se você for um mantenedor ou desenvolvedor principal em um projeto que não está em produção e estiver adicionando código ou alterando seu próprio código, às vezes é desnecessário ter suas PRs revisadas por colegas e geralmente é ok mesclar suas próprias PRs sem uma revisão por colegas.

Intercalando Solicitações Pull

Mescle somente suas próprias solicitações de pull. Se a pessoa que abriu a Solicitação de pull tiver a capacidade de mesclar sua própria Solicitação de pull, o autor do código será a pessoa ideal para mesclar. Há situações em que o autor declara especificamente que isso pode e deve ser mesclado por outra pessoa, e nesses casos, um mantenedor (desenvolvedor principal) do projeto deve se sentir livre para mesclar uma solicitação de pull.
Mesmo que uma solicitação de pull seja aprovada, você sempre deve verificar com o autor da solicitação de pull se eles estão prontos para mesclar.
Para trabalhos ainda em andamento, abrir uma Solicitação de pull de rascunho também ajuda a impedir mesclagens acidentais.

Ramificações compartilhadas

É uma boa prática considerar ramificações para solicitações de baixa automática individuais como um local inicialmente privado do desenvolvedor que criou a ramificação. Não basta enviar para as ramificações de outros desenvolvedores sem ter sido convidado a fazê-lo. Há situações em que as pessoas estão colaborando em solicitações de pull, mas isso deve ser um acordo explícito.

(Dimensionado) Desenvolvimento baseado em tronco

O AEM funciona perfeitamente em um desenvolvimento dimensionado baseado em tronco com desenvolvedores integrados e CI/CD. Isso significa que você mescla um grande número de pequenas solicitações de baixa automática no principal (produção), mas os esforços de Assurance de qualidade/Revisão podem ser adaptados ao impacto de uma pequena alteração. Ninguém quer revisar e testar grandes solicitações de baixa automática, e ramificações de longa vida com muitas alterações tendem a ser difíceis (e perigosas) de mesclar.

Linting

Não altere as configurações de listas (eslint airbnb-base e stylelint), a menos que tenha um bom motivo. A preferência pessoal não é um bom motivo. Alterar a lista torna muito difícil mover os desenvolvedores de projeto para projeto. Argumentar se algo é um bom motivo para alterar a configuração da lista geralmente é muito mais esforço do que simplesmente dizer não categoricamente.

CSS

Isolamento de blocos do seletor de CSS

Os blocos do AEM geralmente operam como componentes colaborativos no mesmo DOM/CSSOM. Isso significa que você deve gravar seus seletores de CSS em um bloco .css de uma forma que impeça que o CSS afete o layout de elementos fora do bloco. A maneira mais fácil de fazer isso é garantir que cada seletor de CSS no .css de um bloco se aplique somente ao bloco.

Em cascata no CSS

Use seus nomes de classe CSS sabiamente. Algumas classes e variáveis CSS são usadas em diferentes blocos, e outras não devem ser usadas fora do seu bloco. A prática recomendada é prefixar classes e variáveis privadas ao bloco com o nome do bloco. Por outro lado, se houver classes CSS e contexto CSS que devem ser herdados (geralmente eles podem ser criados), essas classes e variáveis não devem receber o prefixo.

Recuo CSS e ordem das propriedades

Fora de uma PR de refatoração de CSS, não altere a sequência nas propriedades ou o recuo nos arquivos CSS que você tocar em uma PR funcional. Cada desenvolvedor tem preferências diferentes na ordem de classificação das propriedades ou no recuo. Verifique se a diferença que você vê na sua PR está isolada das alterações que você realmente deseja revisar antes de enviá-la.

Complexidade dos seletores de CSS

Não permita que seus Seletores de CSS se tornem complexos e ilegíveis. Geralmente, é melhor decorar classes/elementos CSS adicionais no DOM e gravar CSS legível. Seletores de CSS complexos também geralmente são mais difíceis de manter e mais frágeis do que os equivalentes no JS.

Nomeação de CSS

Nomear suas classes como simples e intuitivas é útil para outros desenvolvedores. Evite o namespace, a menos que seja necessário no escopo de um projeto. Muitas vezes, não há necessidade de especificar o tipo ou a origem (p. ex. o nome do seu sistema de design) de uma variável CSS que deve ser usada em todo o projeto.

Aproveitar atributos ARIA para estilo

Em muitas situações, você adicionará atributos ARIA para acessibilidade. Como esses têm semânticas bem definidas, como expanded ou hidden, que são compreendidas por todos os desenvolvedores, na maioria dos casos, não há necessidade de criar classes adicionais em seu vocabulário que tenham semânticas desconhecidas.

Dispositivo móvel primeiro

Geralmente, os projetos da Web devem ser desenvolvidos "Mobile First". Isso significa que o CSS sem consulta de mídia deve renderizar um site móvel. Adicionar consultas de mídia para estender o layout para tablet e desktop.

Pontos de interrupção

Geralmente, use 600px, 900px e 1200px como seus pontos de interrupção, todos min-width. Não misture min-width e max-width. Use pontos de interrupção diferentes apenas em casos excepcionais, quando você entender bem por que isso é necessário.

Menos, Sass, PostCSS, Tailwind e amigos.

Se estiver trabalhando no contexto de uma organização maior, certifique-se de não introduzir uma dependência em qualquer pré-processador CSS ou estrutura de sua preferência pessoal sem obter a adesão de toda a equipe e organização. Como há muitas preferências pessoais diferentes nessa área, torna-se difícil manter o código se cada projeto ou cada bloco dentro de um projeto usa tecnologias diferentes.
A solução mais simples é contar com o recurso CSS cada vez maior, compatível com os navegadores.

Recursos modernos de CSS

Verifique se os recursos que você está usando são compatíveis com navegadores sempre verdes. Dependendo dos recursos, um suporte mais ou menos difundido pode ser aceitável.

JavaScript

Estruturas

Na maioria dos sites, as estruturas são um exagero para problemas simples de layout fora da funcionalidade semelhante a aplicativos. As estruturas frequentemente apresentam problemas de desempenho da Web (Lighthouse e Core Web Vitals), especialmente se estiverem no caminho do LCP ou introduzirem o TBT, ao tentar resolver problemas triviais. Mantenha as coisas simples.
Se estiver usando estruturas Javascript, certifique-se de não introduzir uma dependência em qualquer estrutura JS ou biblioteca de sua preferência pessoal sem obter a adesão de toda a equipe e organização. Como há muitas preferências pessoais, torna-se difícil manter o código se cada projeto ou cada bloco dentro de um projeto usa tecnologias diferentes.
A solução mais simples é contar com o aumento dos recursos compatíveis com os navegadores.

Criar cadeia de ferramentas

Diferenciar as cadeias de ferramentas de criação de projeto para projeto dificulta a integração de novos desenvolvedores e geralmente apresenta mais complexidade. Certifique-se de não introduzir uma dependência de sua preferência pessoal sem obter a adesão de toda a equipe e organização.
A solução mais simples é manter o projeto inteiro sem compilação.

Recursos modernos do JavaScript

Verifique se os recursos que você está usando são compatíveis com navegadores sempre verdes. Dependendo dos recursos, um suporte mais ou menos difundido pode ser aceitável. Embora o AEM possa ser usado com qualquer navegador, o lib-franklin.js tem uma dependência em navegadores que oferecem suporte ao import() dinâmico. Qualquer recurso que seja suportado pelo conjunto de navegadores que suportam import() dinâmico deve ser considerado seguro. Tecnicamente, é claro, navegadores mais antigos (por exemplo, IE) podem ser compatíveis com projetos do AEM, mas exigem personalização avançada.

Nem todos os recursos têm as mesmas consequências se um navegador não oferecer suporte a eles, alguns podem ser cosméticos e outros podem impedir o funcionamento do site. Um exemplo comum é o "encadeamento opcional". Se um navegador não for compatível com "encadeamento opcional", um único uso pode ter consequências fatais para toda a página.

Carregamento de bibliotecas de terceiros

Não adicione bibliotecas de terceiros ao seu <head> via head.html, pois elas estarão no caminho crítico de carregamento de conteúdo acima da dobra e frequentemente serão carregadas quando não forem necessárias. Adicione as dependências onde for necessário via loadScript() ao bloco específico que tem o requisito correspondente.
No caso de bibliotecas maiores de terceiros, talvez você queira considerar o uso de um IntersectionObserver para garantir que você só as carregue quando o bloco, dependendo dele, estiver sendo rolado para a exibição.

Biblioteca da AEM (aem.js)

A biblioteca AEM (geralmente hospedada em aem.js em um projeto) não está minificada nem ofuscada no momento para facilitar a depuração. Desincentivamos fazer alterações nele com base em projetos e, em vez disso, recomendamos que as extensões específicas do projeto sejam mantidas fora da biblioteca. Agradecemos as Solicitações de pull pelo github, caso você queira propor alterações/correções de erros universalmente aplicáveis.

<head>

O <head> fornecido pelo servidor como parte da marcação do HTML deve permanecer mínimo e sem tecnologia de marketing, como o Adobe Web SDK, o Google Tag Manager ou outros scripts de terceiros, devido a impactos no desempenho. Adicionar scripts ou estilos embutidos ao <head> também não é aconselhável por motivos de desempenho e gerenciamento de código.

Minificação

Normalmente, isso é uma complexidade adicional sem muitos benefícios, a menos que você tenha arquivos JS/CSS realmente grandes, que novamente seriam um antipadrão. Com o Edge Delivery, a forma como o código é estruturado em torno dos blocos, os arquivos geralmente devem ser de pequeno tamanho e a minificação não deve fazer muita diferença. É possível comparar o LHS antes/depois da minificação.
A minificação torna o código um pouco mais difícil de depurar e você precisaria de mapas de origem. Além disso, a minificação requer uma etapa de compilação adicional, o que pode retardar o trabalho de desenvolvimento do site. Portanto, você só desejará chegar lá se houver um benefício tangível dessa complexidade adicional

Conteúdo no Sharepoint/Google Drive

Inicie seu desenvolvimento com Conteúdo

Antes de escrever uma linha de código, crie seu conteúdo (exemplo) em um documento do Word ou Google (ou planilha). Sinta-se bem para a criação e compartilhe-a com as pessoas de sua equipe que têm experiência em apoiar os autores. Exige experiência de suporte para entender quais estruturas de conteúdo são fáceis de entender e recriar pelos autores. Depois de estabelecer uma estrutura de conteúdo que contém todos os elementos necessários para o bloco e analisá-la, você pode começar a desenvolver o código CSS e JS.

Uso /drafts

O ciclo de vida do conteúdo é muito diferente do ciclo de vida do código. Se você estiver propondo alterações em uma estrutura de conteúdo existente no seu código ou criar um novo bloco, não faça apenas essas alterações na página em que está trabalhando. Copie a página na pasta /drafts/<yourname>/ e faça as alterações nela.
Depois que suas alterações de código forem mescladas com o main, você poderá fazer com que os autores copiem ou mescle seu conteúdo com o conteúdo fora da sua pasta do /drafts/.

Compatibilidade com versões anteriores de novos recursos

Especialmente em ambientes de produção, é importante manter as alterações previstas na estrutura de conteúdo compatíveis com o conteúdo existente. Idealmente, o código que está sendo mesclado não deve ter impacto no site ou exigir a refatoração do conteúdo. Somente quando o novo conteúdo é implementado por meio de um ciclo de pré-visualização e publicação, a nova funcionalidade fica disponível. Isso, claro, não se aplica a coisas como alterações de design no conteúdo existente ou correções de erros funcionais.

Usar conteúdo para recursos "estáticos"

Geralmente, não é uma boa ideia confirmar binários no repositório do GitHub. Mesmo recursos estáticos baseados em texto, por exemplo, arquivos HTML ou SVGs, só devem ser colocados no GitHub em casos excepcionais. Um bom motivo para adicionar uma SVG ao repositório Git é se ela for referenciada do código. Não confirme nada que esteja relacionado ao processo de criação de conteúdo ou que possa fazer parte de um processo de criação. Há algumas exceções (geralmente relacionadas a clientes herdados e não navegadores) que exigem um determinado conjunto de recursos fixos que não podem ser produzidos e manipulados dinamicamente pelo AEM, mas em geral se você encontrar um grande conjunto de recursos estáticos (por exemplo, imagens, etc.) ou um arquivo HTML em uma PR, provavelmente não é uma boa prática.

Usar conteúdo para cadeias de caracteres / literais

As cadeias de caracteres exibidas para os usuários finais e que podem ser traduzidas ou alteradas em algum momento devem sempre ser autorais e provenientes de conteúdo (por exemplo, placeholders ou outras planilhas ou documentos). Se você tiver uma sequência literal que é exibida como texto para o visitante do seu site no seu código javascript ou css, é uma boa prática substituí-la por uma referência ao conteúdo (por exemplo, placeholders).