Este é o primeiro post relacionado à engenharia detalhando um passo a passo do que construímos, e nada melhor do que blogar sobre como reconstruir nosso blog em nosso novo blog? Quão meta. Tudo começou com um blog de engenharia Alguns meses...
Ontem, anunciamos a reformulação do nosso blog e a adição do nosso canal de engenharia. Este é o primeiro post relacionado à engenharia detalhando um passo a passo do que construímos, e nada melhor do que blogar sobre como reconstruir nosso blog em nosso novo blog? Quão meta.
Tudo começou com um blog de ciência e engenharia
Alguns meses atrás, assumi uma função de fato liderando os esforços de evangelismo de desenvolvedor no Avance Network. Digo isso com uma advertência: tratamos o evangelismo do desenvolvedor no Avance de maneira muito diferente do que a maioria das outras empresas. O que nós não fazemosquero fazer é criar uma equipe de pessoas que viaje, fale em eventos, tente vender algo e código ocasionalmente - isso não fazia sentido para nós. Em vez disso, o que realmente queremos fazer é destacar o incrível trabalho de alcance público que os membros de nossa equipe de engenharia já estão fazendo. A maioria, senão todos, os nossos desenvolvedores são membros ativos não apenas do Avance Network, mas da comunidade técnica mais ampla: escrevendo posts em blogs, fazendo trabalho de código aberto e falando em conferências. Nós realmente queremos lançar alguma luz sobre os esforços individuais de alcance público que nossa equipe de engenharia está fazendo ativamente. Em segundo lugar, queremos tornar mais amplamente conhecida a filosofia que tornou o Avance Network tão bem-sucedido para a comunidade de cientistas da computação desenvolvedores e engenheiros da computação. Quem melhor para fazer isso do que os desenvolvedores que ajudaram a formar essa comunidade?
Portanto, a primeira solução natural para abordar esses objetivos seria um blog sobre o trabalho que estamos fazendo. Fomos inspirados por vários blogs técnicos excelentes como Code as Craft e OkTrendse a ideia de um blog de engenharia semelhante a esses exemplos foi lançada. No entanto, havia reservas quanto à criação de um blog completamente separado: por que fragmentar ainda mais nossos leitores? Tínhamos o blog oficial da empresa Avance Network, o blog ServerFault de nossa equipe SRE e os muitos blogs pessoais que nossos desenvolvedores individuais tinham. Havia tantos caminhos diferentes para publicar nosso trabalho, e não podíamos descobrir onde esse conteúdo iria morar. Parecia que, se criássemos novos tipos de conteúdo em um blog completamente separado, o ecossistema existente nos forçaria a fragmentar ainda mais nosso público. Caso contrário, hospedaríamos conteúdo simplesmente impróprio em um dos blogs existentes. O que nós realmente o necessário era um único destino que pudesse acomodar muitos tipos diferentes de conteúdo, em vez de criar vários destinos especializados em apenas um tipo.
Revisitando o blog e página do Avance Network
Depois de enviar a proposta original para a empresa, percebi rapidamente que poderia ter pisado em uma mina terrestre de um projeto. O ecossistema do blog era algo que desejávamos abordar há muito tempo, e isso significava que praticamente todas as partes da empresa seriam afetadas por ele e tivessem opiniões fortes sobre o projeto. Depois de considerar todos os comentários que recebi, chegamos a uma conclusão geral: a solução ideal seria pegar nosso blog mais popular, o blog oficial do Avance Network, e usá-lo para hospedar o novo conteúdo que queríamos - incluindo as postagens de engenharia. Acabou sendo um projeto muito maior que levou de seis a oito semanas . Havia algumas partes importantes para essa solução que a fariam funcionar:
Canais
No blog anterior, tínhamos todas as nossas postagens em uma única coluna organizada por tag. Isso significava que tudo o que postamos iria para qualquer pessoa que estivesse lendo nosso blog. A preocupação aqui era que se começássemos a escrever postagens muito técnicas e as colocássemos neste canal, seria relevante para um subconjunto técnico de nosso público, mas não para todos. Por outro lado, os desenvolvedores que viriam ao nosso blog para ler conteúdo técnico não iriam necessariamente querer ler ou se preocupar com tudo o mais que estamos fazendo - eles estão aqui para o material de engenharia.
O que criamos foram “canais” - categorias de alto nível que nos permitiriam separar os principais tipos de postagens que publicaríamos. Existem dois principais: notícias da empresa e engenharia. O canal de notícias da empresa abrigaria todo o conteúdo familiar, como podcasts, anúncios da empresa e assim por diante. Também nos permitiria adicionar novos tipos de conteúdo, como aqueles para a cultura interna e esforços relacionados à diversidade. O canal de engenharia tornou-se efetivamente nossa solução para um blog de engenharia e hospedaria todos os nossos percursos técnicos, redações de esforços de evangelismo e artigos de opinião técnica como queríamos originalmente.
Repostagens
Outra parte importante desta solução foi a capacidade de repostagem. Muitas das postagens mais populares relacionadas ao Avance Network - especialmente as postagens técnicas - foram descentralizadas, alojadas em nossos muitos blogs pessoais de desenvolvedores. Houve um bom motivo para isso: acreditamos que nossos desenvolvedores deveriam receber publicamente o crédito pelas coisas que constroem internamente, e uma das melhores maneiras de reivindicar isso é escrever sobre isso em seus blogs pessoais. Depois de criar um canal de engenharia, não queríamos que nossos desenvolvedores sentissem que precisavam escolher entre postar no blog da empresa ou em seu blog pessoal. Parecia o movimento errado.
Em vez disso, sugerimos uma abordagem diferente: poste em seu blog pessoal sobre o seu trabalho como sempre fez e, se quiser postar novamente no blog da empresa para obter mais exposição, faremos isso com um link destacado para a fonte original . Ele faz duas coisas: dá ao nosso público técnico a capacidade de ver por dentro como construímos as coisas, dando ainda crédito às pessoas que as constroem.
Um novo motor de blog
Durante a fase de proposta original para o blog de engenharia, também conversamos sobre qual motor usaríamos. Na época, todos os nossos blogs rodavam WordPress ... com o qual não estávamos tão felizes. Era muito problemático, difícil de fazer login, não tinha muito desempenho e causou à nossa equipe SRE mais do que algumas dores de cabeça. Se realmente íamos renovar o novo blog da empresa, parecia muito trabalhoso tentar e lutar com a instalação do WordPress.
Construindo o blog
Tudo bem - o suficiente sobre o processo de ideação. Agora, para as partes técnicas substanciais. Houve muito trabalho de desenvolvimento envolvido nisso, então irei destacar apenas algumas das principais peças e percepções que tivemos ao construir o blog:
A infraestrutura
Começar um projeto Jekyll é bastante simples. É ridiculamente fácil de instalar e com apenas algumas convenções de nomenclatura na estrutura do arquivo, Jekyll cuida da geração estática do site. Por mais fácil que seja, decidi criar um fork de um repositório de bootstrapping existente chamado Jekyll Now feito por um amigo meu (e VP de Engenharia da Trello), Barry Clark .
Fora da caixa, a maior parte do que precisávamos estava lá: um mecanismo de postagem com Markdown e suporte a realce de código, flexibilidade de JavaScript e CSS, e era rápido . Como todo o trabalho duro estava sendo feito no início, estávamos apenas servindo arquivos estáticos e isso foi um grande aumento de desempenho em relação ao WordPress. Em apenas alguns minutos, eu tinha um blog básico de trabalho que estava sendo hospedado nas páginas do GitHub. Já estávamos no bom caminho para o que tínhamos originalmente planejado fazer.
Importando o conteúdo antigo
Mover todos os nossos posts anteriores para a nova solução era um requisito difícil, e isso significava pegar todo o conteúdo que tínhamos em nossa instância do WordPress e convertê-lo em arquivos no Markdown. Isso não foi fácil: tivemos mais de 700 postagens de blog ao longo da história da empresa, cada uma com comentários, ativos estáticos e links diretos que precisavam ser preservados. O processo parecia bastante simples, se não crivado de casos extremos que precisavam ser resolvidos: o WordPress tem uma função de exportação que gera um arquivo XML gigante (incríveis 30 MB de texto e só tivemos que usar esse arquivo para converter e extrair arquivos.
Felizmente, existem algumas bibliotecas que tornam essa migração mais fácil. Tentei alguns dos métodos de importação recomendados na documentação do Jekyll, mas nenhum deles parecia fazer isso de forma limpa. Depois de mais algumas tentativas, finalmente descobri exitwp e isso pareceu funcionar muito bem. Você pode ver o commit aqui - foram mais de 5.000 alterações de arquivos diferentes com a importação inicial.
Na maior parte, isso funcionou muito bem. Fiquei surpreso com o quanto foi preservado e o fato de que Jekyll suporta HTML arbitrário nos arquivos Markdown ajudou muito. No entanto, algumas coisas foram perdidas no processo: algumas imagens com legendas foram formatadas incorretamente, as incorporações foram perdidas para muitos de nossos podcasts e as referências a arquivos carregados no WordPress quebraram as imagens em todo o quadro.
Foi quando eu realmente tive que intervir programaticamente. Comecei a escrever scripts Python para passar por cada postagem e reparar muito do trabalho feito aqui. Esta é a visão geral de alto nível:
Para erros de HTML, muito desse trabalho de reparo era manual. Analisamos as 50 principais postagens de alto tráfego e as 100 postagens mais recentes e analisamos manualmente para garantir que tudo estava bem formatado. Isso foi feito com muita ajuda de nossa equipe de marketing.
Eu escrevi um script Python para percorrer todas as postagens importadas, procurei referências ao conteúdo hospedado em WordPress, baixei todos os ativos estáticos images/wordpressno repositório e alterei todos os links para caminhos relativos no Jekyll. Funcionou surpreendentemente bem.
Usamos incorporações do Soundcloud para todos os nossos podcasts, e a grande maioria deles estava quebrada. Eu escrevi um script Python que usava uma expressão regular para encontrar o URL relevante para o embed e reinseri o código necessário para restaurar o player. Você pode ver o código para isso abaixo. É muito semelhante ao código que escrevi para a importação de imagens também.
{% destaque Python%}
import os, re, requests
rootdir = '_posts'
para subdir, dirs, arquivos em os.walk (rootdir):
para arquivo em arquivos:
filename = os.path.join (subdir, arquivo)
f = open(filename, "r")
contents = f.readlines()
f.close()
# Get WordPress
slug = filename.replace("_posts/", "").replace(".markdown", "")
splits = slug.split("-")
year = splits[0]
month = splits[1]
end = "-".join(splits[3:])
link = "/".join([year, month, end])
link = "/" + link
wordpress_url = "http://avance10.com/" + link
if re.search('podcast', wordpress_url):
print wordpress_url
response = requests.get(wordpress_url)
if response:
for line in response.content.split("n"):
if re.search('iframe|object', line) and re.search("soundcloud", line):
contents.append('n'+line)
f = open(filename, "w")
f.write("".join(contents))
f.close()
continue
contents.append(iframe)
f = open(filename, "w")
f.write("".join(contents))
f.close()
{% endhighlight%}
Feeds e links
Outro requisito difícil era garantir que não quebrássemos o deep linking. As postagens em nosso blog são bastante referenciadas na rede Avance Network, bem como na Internet em geral. Quebrar nosso esquema de URL para postagens teria sido absolutamente desastroso. Além disso, precisávamos preservar o feed XML em nosso blog. Existem integrações para o boletim da comunidade, é uma dependência de partes dos próprios sites do Avance Network e há milhares de pessoas que contam com o feed para receber nossas notícias. Preservar os links para nosso conteúdo e pelo menos nosso feed principal foi extremamente importante.
Novamente, Jekyll felizmente tinha um recurso para personalizar estruturas de URL de postagem. Isso era simplesmente uma configuração em nosso _config.ymlarquivo e exigia uma única linha de código:
{% destaque ruby%}
link permanente: /: ano /: mês /: título /
{% endhighlight%}
A alimentação era um pouco mais complicada. Dando uma olhada no feed XML que tínhamos antes, tivemos que nos certificar de que todos os dados necessários foram preservados, mas não havia nenhuma funcionalidade nativa no Jekyll que pudesse atender às nossas necessidades. No entanto, havia uma solução alternativa à vista. O mecanismo de modelagem de Jekyll não era bom apenas para pegar Markdown e analisá-lo em HTML; ele pode ser usado para criar arquivos estáticos arbitrários que foram expostos no site. Isso significa que eu poderia apenas criar algo como /feed/index.xmle usar a linguagem de modelos para gerar um feed! Isto é o que parece:
Paginação
Este foi realmente um dos desafios técnicos mais fascinantes que encontrei. Como mencionei antes, temos mais de 700 postagens em nosso blog, e isso só iria crescer, provavelmente a uma velocidade ainda maior. Era simplesmente irracional deixar de fora o suporte à paginação. Infelizmente, Jekyll tem apenas suporte limitado para paginação. Isso poderia funcionar razoavelmente bem para todas as postagens, mas precisávamos de uma paginação de granulação mais fina que também filtraria por autor e tag. Além da falta de customização para paginação, usar o recurso nativo realmentediminuiu o tempo de construção. As páginas passavam por cada postagem, cada tag e todos os outros arquivos tentando gerar HTML para cada permutação. Nosso tempo de construção para todos os posts passou de cerca de 5 segundos a vários minutos, porque a geração de Jekyll estava demorando MxNxO. Simplesmente não havia boas soluções para isso nativamente ou que outras pessoas resolveram com as bibliotecas que pude encontrar.
Então terminei tentando algo completamente diferente. Em vez de depender do Jekyll para gerar estaticamente cada página inicial, decidi gerar JSON com todas as postagens e seus metadados, depois carregar lentamente esse JSON via AJAX e filtrar usando as tags e os autores dessa postagem. Isso significava que apenas um arquivo precisava ser gerado em vez de cada permutação, havia mais flexibilidade programática com JavaScript para filtrar e poderíamos injetar paginação em qualquer página para qualquer conjunto de postagens que quiséssemos.
Pensamentos finais
Este foi um projeto muito maior do que eu havia previsto inicialmente, mas estou muito feliz com os resultados. O feedback inicial foi muito positivo e, embora houvesse inevitavelmente bugs com uma migração tão grande, com o Meta e o código de código aberto, estamos corrigindo-os rapidamente. Já recebemos solicitações pull com alterações e correções de bugs.
No final, estou feliz por finalmente haver um único destino para nossa equipe de engenharia alcançar a comunidade técnica da qual amamos fazer parte. Você verá muito mais conteúdo como este de nossa equipe de cientistas e engenheiros no futuro, e adoraríamos ouvir seus comentários. Até a próxima vez!
O Avance Network é uma comunidade fácil de usar que fornece segurança de primeira e não requer muito conhecimento técnico. Com uma conta, você pode proteger sua comunicação e seus dispositivos. O Avance Network não mantém registros de seus dados; portanto, você pode ter certeza de que tudo o que sai do seu dispositivo chega ao outro lado sem inspeção.
