Esse tutorial foi escrito por Anicely Santos, com sugestões de Fernanda Souza, em setembro de 2022.
Você já parou para pensar no tanto de bibliotecas, projetos e ferramentas que existem disponíveis para facilitar o dia a dia da pessoa que trabalha com dados ou qualquer outro segmento? Sobre isso tenho uma notícia boa e uma ruim para você: A boa é que diariamente coisas novas estão sendo criadas com esse objetivo. A ruim é que nem todas elas conseguirão avançar muito. Isso porque, quer seja um projeto, quer seja uma biblioteca, pacote, ferramenta, ou até mesmo um site, é necessário ter pessoas mantenedoras.
Esse tutorial pretende, a partir do conhecimento da plataforma GitHub e da ferramenta Git dentro do Visual Studio Code, auxiliar pessoas a colaborarem em projetos de código aberto, para que estes mantenham-se sempre atualizados. Faremos isso enquanto contribuímos incluindo mais uma ferramenta na Caixa de Ferramentas. Algumas ações feitas neste tutorial também é possível ser executada utilizando o site do GitHub ou a versão da plataforma para Desktop.
CONTROLE DE VERSÃO
Antes de colocar a mão na massa, é importante saber uma das principais funções da ferramenta Git, o controle de versão. Pois bem, controle de versão nada mais é do que uma “viagem no tempo”.
Certamente você já teve ter passado pela experiência de salvar cada versão de um projeto com vários nomes (agora vai.doc, versão final final.doc, versão final de verdade.doc), para garantir as alterações. Ferramentas de controle de versão fazem exatamente isso. A diferença é que elas “mapeiam” cada alteração com uma chave única (hash) possibilitando que você volte quantas vezes considerar necessário para a etapa que desejar e inclua alterações a partir dali, em um único arquivo, mais ou menos como a opção Histórico de versões no Google Docs.
O MUNDO COLABORATIVO DO GITHUB
O GitHub é uma das plataformas mais populares para armazenamento de projetos de código aberto e colaborações. As funcionalidades são muitas, aqui vamos tentar entender o que é necessário para começar a dar os primeiros passos nesse mundo de contribuições.
Antes de mais nada, acesse a plataforma https://github.com/signup e crie uma conta.
Assumindo que você já está logado, vamos iniciar o nosso passeio. Logo em cima na tela, teremos essa barrinha.
Nesse espaço de pesquisa, ao lado do logo do GitHub, é possível fazer buscas por projetos, pessoas e organizações.
Seguindo temos Pull requests que mostra todas as solicitações de alterações que você fez para algum projeto. Sempre que quiser contribuir em projetos, é um Pull request (ou PR) que você precisará submeter. Não se preocupe, veremos como fazer isso mais para frente.
Em seguida temos Issues que basicamente são pontos que precisam ser resolvidos em um projeto. Esse menu mostra todas as Issues que você abriu ou fechou em algum projeto.
Do lado direito, mais abaixo, encontramos a opção Create your first project. Essa opção serve para você criar um repositório (ou importar um já existente) para armazenar o que você quiser.
A construção de um repositório é bem simples e intuitiva. Basicamente você vai dizer de qual conta você quer criar o repositório, caso tenha mais de uma (Owner) e colocará um nome no repositório (Repository name), isso são ações obrigatórias, as demais funções são opcionais. Vou explicar algumas delas consideradas importantes em um projeto.
- Description: Aqui se descreve de maneira resumida o que está sendo armazenado nesse repositório, informações que aparecerão no About ao lado do repositório quando este estiver aberto.
- Public ou Private: Sinaliza quem pode visualizar o repositório: você e pessoas específicas (Private) ou todo mundo (Public).
- Add a README file: Nesse arquivo você pode documentar detalhadamente informações sobre o seu projeto e como as pessoas podem contribuir com ele. É um arquivo que pode ser incluído depois, mas é super importante sua existência. É aqui onde as pessoas conseguirão entender e se interessar pelo projeto. Um README bem feito pode render muitas contribuições.
- Choose a license: O tipo de licença vai sinalizar que tipo de ação as pessoas podem fazer com seu código (se podem replicar inteiro ou só uma parte, por exemplo). Tem várias opções, você pode ler melhor neste artigo.
No meio você pode ver alguns primeiros passos para fazer na sua recém criada conta.
Se você já tivesse seguindo pessoas ou organizações, nesse espaço apareceriam as atualizações relacionadas a essas conexões. Sugiro que você explore um pouco e personalize sua página inicial, siga algumas pessoas e depois volte aqui para continuarmos.
CONHECENDO UM REPOSITÓRIO
Toda página de um repositório armazenado no GitHub possui a mesma estrutura, o que vai mudar são as personalizações. Para visualizar essas opções, utilizaremos como base o repositório da Caixa de Ferramentas de Jornalismo de Dados que está armazenado na página da Escola de Dados no GitHub.
Estando na página do repositório, do lado superior esquerdo temos o nome da pessoa proprietária do projeto / nome do projeto, seguido da sinalização se é um projeto público (public) ou privado (private). Tudo isso são aquelas informações que você indica assim que cria um repositório.
Logo abaixo você verá uma tela que possui informações importantes sobre tempo do projeto, contribuições, arquivos. Veja a descrição de algumas partes.
- Main: Esse menu é onde ficam as ramificações (branches). Lembra da história de controle de versão? Então, as versões ficarão gravadas nessas ramificações. Por padrão, todo repositório começa com uma ramificação – a main – mas é possível criar várias (observe que ao lado sinaliza que existem 4 branches) e, se desejar, uni-las em uma só (merge).
- Add file: Cria um novo arquivo no repositório.
- Upload file: Altera um arquivo já existente no repositório.
- Code: ao clicar nessa opção, vai abrir um pequeno menu que dará opção para clonar o repositório via linha de comando a partir de um link, abrir o repositório na versão GitHub Desktop ou baixar o projeto compactado (Download ZIP).
Dentro da caixa principal do repositório, você tem todos os arquivos e pastas do projeto. No meio tem todas as mensagens de atualização dos arquivos (commits) e do lado direito tem quando essas atualizações aconteceram. Essa área toda é o conteúdo do seu repositório, uma espécie de fotografia de tudo que já aconteceu com ele desde o seu início.
Abaixo dessa tela temos o README.md. É muito importante ler esse arquivo antes de qualquer coisa, pois é ele quem te dirá tudo que você precisa ter e fazer para contribuir. E é sempre importante manter esse arquivo atualizado.
A contribuição que faremos vai ser seguindo essa documentação. Lá existem duas opções de contribuição, faremos a que utiliza Git. Uma dica muito importante para projetos em geral: explore o repositório e leia bem a documentação.
PREPARANDO O AMBIENTE
Agora que já conhecemos um pouco como é a plataforma GitHub e já conhecemos melhor o projeto que queremos contribuir, vamos preparar o ambiente para iniciar as contribuições. Começaremos instalando o Visual Studio Code para conseguirmos manipular os arquivos e o Git para mapear as mudanças que faremos.
Para instalar o Visual Studio Code acesse a página da ferramenta (https://code.visualstudio.com/) e no canto superior direito clique em Download. Na página seguinte, escolha a versão disponível para seu Sistema Operacional e faça a instalação que é super simples, apenas clicando em próximo (next) até concluir.
Concluída a instalação, agora acesse a página do Git, rolando um pouco para baixo, na página principal. Escolha a versão que atende ao seu Sistema Operacional clicando em Downloads ou clicando na imagem do computador (que geralmente detecta qual o Sistema Operacional e indica a instalação específica). O procedimento é o mesmo: próximo (next) até concluir.
Para se certificar que a instalação foi bem sucedida, abra o Visual Studio Code, na barra de menus, logo em cima, escolha Terminal > Novo Terminal. O terminal será aberto logo abaixo. Dentro do Terminal digite git —version, sendo o traço dois sinais de menos (-). Se tudo ocorreu bem deve aparecer a versão de git instalado na sua máquina.
Algo muito importante sobre o mundo Git é que todos os comandos sempre iniciarão com a palavra git seguido do que você quer fazer.
COLABORANDO COM UM PROJETO
Vamos clonar o repositório para nossa máquina. Iremos trabalhar localmente e depois enviaremos a alteração, que no nosso caso será enviar mais uma ferramenta para a plataforma.
Antes de clonar o repositório, crie uma pasta no seu computador onde você deseja armazenar o projeto clonado. Volte para o Visual Studio Code, na barra de menus, escolha Arquivo > Abrir pasta… dentro da caixa que abre, navegue até a pasta que você criou e escolha Selecionar pasta. Deve aparecer uma tela perguntando se você confia nos autores da pasta, selecione Sim, confio nos autores.
Observe agora que no Terminal deve aparecer o caminho da pasta que você escolheu para clonar o projeto. Isso significa que tudo que fizermos será feito dentro dessa pasta.
O Git utiliza o seguinte padrão para clone de projeto:
git clone <link do projeto a ser clonado>
O link do projeto a ser clonado não deve ser o endereço do navegador. Lembra do botão verde Code que aparece no repositório? Clicando nele vai aparecer várias alternativas para baixar uma versão. A que queremos é a primeira opção, que tem o nome HTTPS selecionado e o link logo abaixo. Copie esse link.
O seu script deve ficar semelhante a esse:
git clone https://github.com/escola-de-dados/toolkit_ddj.git
Feito isso, tecle enter.
Após clonar, agora temos uma versão do projeto em nossa máquina. Dentro do Visual Studio Code, do lado superior esquerdo, você encontrará alguns ícones. De cima para baixo temos o “Explorador”. Clicando nele você consegue visualizar todo conteúdo da pasta aberta que você clonou.
Antes de qualquer modificação, a documentação do projeto nos indica mudar o ramo (branch) em que estamos para um novo, seguindo o padrão de acordo com o que queremos:
- SEU_USUARIO/addTool – Para adicionar uma ou mais novas ferramentas.
- SEU_USUARIO/updateTool – Para atualizar os dados de uma ou mais ferramentas.
Atualmente estamos utilizando a main, que é a branch principal do projeto. Como eu sei disso? Coloquei git branch e ele me informou em qual rama estou trabalhando no momento. Se tivessem mais de uma, ele mostraria todas e indicaria a branch ativa utilizando um asterisco ao lado do nome.
Queremos incluir uma ferramenta, então usaremos a primeira opção (add/Tool). Criaremos uma branch nova e já ativaremos para começar a trabalhar com ela. O comando para fazer isso é o seguinte:
git checkout -b <nome da nova branch>
Seguindo o padrão ali em cima de como nomear a branch para incluir uma ferramenta, teremos:
git checkout -b escola-de-dados/addTool
Onde escola-de-dados será substituído pelo seu nome de usuária no GitHub. Se o procedimento deu certo, deve aparecer a mensagem Switched to a new branch ‘<nome da branch>’.
Agora com uma branch nova já ativa, podemos incluir uma nova ferramenta.
Nessa estrutura de pastas, seguindo a documentação do projeto, o que nos interessa é o arquivo tools.yml, que se encontra no caminho docs/data/tools.yml. Navegue até lá e clique nele. Ao clicar, o arquivo deve abrir do lado direito.
Se você for na documentação do projeto, entenderá o que significa cada campo, que se repete em blocos, sendo cada bloco uma ferramenta. Tudo que precisamos fazer é ir até o final e incluir mais um bloco desse preenchido.
No momento em que estamos fazendo esse tutorial, a última ferramenta é a de id 156. Vamos copiar um bloco, colar no final da lista e mudar as informações dos parâmetros para incluir a ferramenta Google Collaboratory.
O bloco da nova ferramenta ficou assim:
Feito isso, tecle Ctrl + S e salve o arquivo.
Observe que ao clicar em salvar, ao lado do arquivo tools.yml na aba Explorador aparece a letra M, indicando que o arquivo foi modificado. Além disso, no ícone Controle de código-fonte (dois ícones abaixo do Explorador) mostra o número 1, mostrando a quantidade de alterações que estão pendentes localmente. Quanto mais alterações forem feitas, mais esse número mudará.
Tudo isso que você viu “graficamente” pode ser visualizado utilizando o comando git status.
Qualquer modificação que você faz na pasta localmente, uma vez que o arquivo é salvo, essas alterações ficam esperando serem salvas no git. Lembra da história de viagem no tempo? Então, são esses “salvamentos” no git que criarão essa linha do tempo.
GRAVANDO AS ALTERAÇÕES VIA GIT
Quando dermos o comando git status, ele mostrará tudo que está aguardando na área de espera (Staging area). Se tiver algum arquivo esperando nessa área, ele sempre aparecerá em duas cores:
- Vermelho – esperando ser adicionado a linha do tempo.
- Verde – Preparado para adicionar a linha do tempo.
Além disso, o git também nos dá opções de comandos para usar nos arquivos que aparecem nessa área. Como o que queremos é salvar nossas contribuições, vamos utilizar o git add.
O git add prepara os arquivos para serem gravados. Se você deseja preparar alguns arquivos específicos nessa área, basta usar git add <nome do arquivo> para cada arquivo que deseja preparar. Caso deseje preparar todos os arquivos, uma opção mais prática é usar git add . (onde o ponto indica que é tudo que está nessa área, sem especificar).
Vamos utilizar o comando git add . para preparar nossas alterações.
Se você colocar git status novamente, verá que o arquivo que antes estava em vermelho, agora está em verde. Logo, está pronto para ser gravado na linha do tempo git.
Para gravar o arquivo, o que popularmente é conhecido como “commitar”, utilizaremos o seguinte comando:
git commit -m “<mensagem de commit>”
Onde a mensagem de commit (que deve estar entre aspas) é alguma frase sobre a alteração que está sendo gravada. Essa mensagem é importante para caso você deseje voltar em algum commit, facilite encontrar também pela mensagem.
Após personalizar o git commit com a mensagem que você deseja, tecle enter. Se você rodar git status agora, verá que não tem nada esperando para ser gravado.
ABRINDO UM PULL REQUEST
Bom, tudo que fizemos até agora foi gravar nossas alterações localmente. Nosso objetivo principal é que o site do projeto tenha nossa ferramenta. Para isso, precisamos enviar nossas alterações para o repositório do projeto lá no GitHub.
Para essa etapa dois comandos são super necessários: git pull e git push. O git pull traz sempre todas as alterações do repositório. É sempre importante dar esse comando toda vez que começar a trabalhar com um repositório que está clonado na sua máquina, para ter certeza que ele está atualizado. Já o git push envia todas modificações feitas localmente para o repositório no GitHub.
Assim como as alterações que fizemos só existem na nossa máquina, a branch que criamos também só existe na nossa máquina. Para enviar as alterações precisamos rodar o seguinte comando:
git push origin <nome da branch que criamos>
Isso só é necessário quando está enviando uma branch nova pela primeira vez. Nas próximas vezes, só precisa rodar git push e as alterações já irão acontecer porque a branch já existirá no repositório remoto.
Feito isso, se tudo deu certo, ao ir no GitHub, abrir o repositório do projeto e clicar logo em cima em main, deve aparecer a branch que você criou.
Perfeito! Nossa branch e alterações já foram enviadas, mas essas alterações ainda não estão adicionadas a branch main, que é a principal do projeto, de onde o site pega as informações. Para solicitar isso, logo acima veremos uma barra de opções onde uma delas é Pull requests.
Ao clicar nela, abrirá uma área que mostrará todos os pull requests abertos. Do lado direito tem a opção New pull request, clique nela.
Vai aparecer uma lista de branchs. Isso acontece porque o que o pull request faz é solicitar que as branches sejam comparadas e sincronizadas (merge) com as alterações. Procure a branch que você criou e clique nela.
Nessa nova área você verá logo em cima de qual branch para qual branch as informações estão sendo enviadas. Logo abaixo o nome do usuário e o commit feito no terminal e logo ao lado tem identificador do commit (hash) que você pode usar para “viajar no tempo” e fazer alterações. Bem no meio abaixo vai mostrar todas as modificações que aconteceram. Volte um pouco acima e clique em Create pull request.
Vai abrir uma caixa para fazer um commit no pull request. Na documentação do projeto tem uma padronização de como proceder para cada caso de alteração.
Após preencher os campos, clique no botão verde Create pull request.
Prontinho, você acaba de fazer uma contribuição em um projeto Open Source. ?
Para facilitar sua vida, vou fazer uma colinha aqui dos comandos git que vimos nesse tutorial e que são úteis para contribuição em qualquer projeto.
O Git não se resume só a esses comandos. Ele possui uma documentação extensa e bem didática de todos os comandos e parâmetros que existem para cada um deles, para resolver vários cenários. Vale a pena investir um tempo explorando essa ferramenta.
CONTINUE CONTRIBUINDO
Além desse projeto, temos também o livro digital “Geodados: Uma introdução digital”, que também aceita contribuições que podem ser feitas tanto assim, quanto direto na plataforma do GitHub. Encorajo você a conhecer e contribuir também com os projetos de Inovação Cívica da Open Knowledge Brasil. E, em caso de dúvidas, você pode criar um novo tópico em nosso Fórum.
