Como exibir o grafo de dependências do seu projeto Android no README

Faça o CI trabalhar para você e assista o seu grafo de dependências ganhar forma

Foto por Alla Hetman no Unsplash

Nos últimos seis meses eu venho trabalhando no meu primeiro app Android altamente modularizado e, durante o desenvolvimento, eu constantemente observo como o grafo de dependências (composto pelos módulos Gradle) tem evoluído. É normal ter uma ideia inicial de como o grafo deve ser, mas novas ideias e problemas inesperados sempre aparecem e fazem com que seja difícil seguir o plano original — acaba sendo normal mover um pouco as coisas, especialmente no começo do projeto. Ser capaz de observar a estrutura atual do grafo ajuda bastante a tomar decisões e seguir em frente.

Olha que bonito.

Bem no começo eu tinha desenhos e fotos de esquemas vindos de discussões com colegas para guiar o meu projeto. Quando o grafo começou a ganhar forma, eu comecei a usar a Gradle task do Jake Wharton para gerar uma representação visual do grafo. Em algum momento eu percebi o quão valioso eram as informações que eu tirava dali: o grafo guiava minhas decisões em onde um módulo novo poderia se encaixar, me ajudava a evitar dependências circulares, e me fazia feliz em ver como o projeto estava crescendo.

Dado o tamanho do projeto, eu percebi que o grafo também seria extremamente útil para alguém que estivesse começando a trabalhar no código. Um dia, enquanto estava trabalhando aleatoriamente no README, pensei: "seria massa ter o grafo aqui, mas seria bem triste ter que atualizar ele manualmente toda hora". Até que eu pensei mais um pouco e a ideia por trás desse post surgiu.

O código

Este gist tem tudo que você precisa, e esse repositório tem um exemplo completo. Segue um passo a passo:

1. Nós precisamos da Gradle task projectDependencyGraph, então o primeiro passo é adicioná-la no projeto e referenciá-la no build raiz.
2. É necessário alterar um detalhe da task: originalmente, ela cria o arquivo dot dentro de rootProject.buildDir, que em geral é ignorado pelo nosso sistema de versionamento. Ao invés disso, podemos usar rootProject.rootDir e manter o grafo em algum diretório do projeto.
3. Com a task integrada, é necessário definir a GitHub action que vai gerar o grafo e fazer o commit e o push:

Estamos usando o GitHub Actions aqui, mas é muito provável que seja possível escrever os mesmos passos com a sua ferramenta favorita.

Existe uma ótima GitHub action que configura o Graphviz, que é a ferramenta usada pela Gradle task para gerar o grafo. Este é o segundo passo: ts-graphviz/setup-graphviz@v1. O terceiro passo é executar a task para gerar o grafo.

Com o grafo gerado, é necessário fazer o commit. Para isso, basta executar alguns comandos Git para configurar o usuário que será o dono do commit e para fazer o commit propriamente dito. É importante que o comando não falhe se não houver mudanças em arquivos (o que pode acontecer caso o grafo não tenha mudado desde sua última atualização), por isso que o comando utilizado é mais complicado que o normal. Não me pergunte como ele funciona, copiei ele daqui 💁‍♂️

Por último, é necessário fazer o push, e felizmente também existe uma action para isso. Apesar da action fazer o push para o master, ela não desencadeia outra execução do workflow mesmo se ele estiver configurado para ser executado a cada push no master, então não é necessário se preocupar com execuções recursivas acidentais.

O grafo

Com a Gradle task e a GitHub action em seus devidos lugares, é possível referenciar o arquivo PNG do grafo no README dessa forma:

O código final vai depender de qual diretório foi escolhido na task, mas é basicamente isso! É bem legal ver a mágica acontecendo:

Quem me dera toda documentação soubesse se atualizar sozinha assim.

Se você curtiu, ou tem alguma ideia de como aplicar o conceito geral em algum outro cenário, me chama no Twitter!