DEV Community: Gustavo Dias Alexandre

Contribuindo com Projetos Open Source

Gustavo Dias Alexandre — Wed, 29 Sep 2021 22:54:38 +0000

Para quem está começando à descobrir o incrível mundo do código aberto (open source), quer ser relevante e contribuir de alguma forma mas, não sabe por onde começar.

Neste tutorial, eu tento passar de forma simples os mecanismos básicos para um bom PR (pull request).

Alguns pontos importantes devem ser levados em consideração:

Ambiente Git;
Conta no Github;
Conhecer e curtir a proposta do projeto;
Fork Clone Branch Add Commit Push PR;
Sincronizar o fork.

Este tutorial vai ser focado nos pontos 3, 4 e 5. Os dois primeiros são pré requisitos para os seguintes, mas não serão os pontos-chave.

Conhecer e curtir a proposta do projeto

Antes de tudo, é legal se identificar com a ideia do projeto, gosto de pensar que "sempre curti utilizar as ferramentas A, B ou C. Vi que elas têm código aberto, vai ser massa contribuir!". Até nos repositórios mais simples, é sempre bom estar em harmonia com a finalidade do projeto e gostar de ajudar.

Outro ponto importantíssimo é ler a documentação e os guias de contribuição, cada repositório tem seus guidelines, how do I contribute?, contributing.md... Então, antes de sair abrindo PRs, é essencial consultar como o pull request deve ser feito.

Aqui vamos tratar apenas do fluxo básico (caminho feliz).

Fork Clone Branch Add Commit Push PR

Estas são as etapas básicas para trabalhar com repositórios, que vai desde a duplicação, modificação até a solicitação de alterações no código original.

Fork

Escolhido o repositório, é hora de fazer o seu Fork!

Um fork/bifurcação nada mais é que uma cópia de um repositório, logo é possível trabalhar e fazer alterações em um repositório bifurcado ("forkado" hahahaha), sem que estas mudanças altere o repo original diretamente.

Feito o fork, haverá um novo repositório criado a partir do original.

É hora de clonar este novo repo!

Clone

Para trabalhar localmente no projeto, é necessário cloná-lo para o seu ambiente (É possível fazer alterações diretamente no browser pelo github, na maioria das vezes não é tão recomendado).

Dentre as opções, dá para clonar via HTTP, SSH ou GitHub CLI. Escrevi um outro material sobre como criar e vincular chaves ssh com o github.

Clone via ssh:

gustavo@linux:~$ git clone <link-repo-fork>

gustavo@linux:~$ git clone git@github.com:gfda/gfda.git

Branch

Geralmente, em projetos compartilhados, alterações de código não são feitas diretamente na branch principal (main). Então, uma boa prática é criar uma branch(ramificação) específica para receber as mudanças. Cada projeto tem suas regras para criação, padrões de nomenclatura, uso de branchs... Isto reforça a necessidade de estar em sincronia com os guias do repo.

Para entender mais sobre branches, fica o link da documentação do git.

Criando a branch:

gustavo@linux:~$ git branch <nome-da-nova-branch>

Mudando para branch:

gustavo@linux:~$ git chcekout <nome-da-nova-branch>

Dica:
É possível combinar os dois comandos acima em um único comando git.

gustavo@linux:~$ git checkout -b <nome-da-nova-branch>

Add -> Commit -> Push -> PULL REQUEST

Já na nova branch, é hora de trabalhar no código!

Cada repositório tem suas regras de commits (ressalto a importância de ler a documentação), mas não é uma boa prática ter grandes mudanças em um único commit/PR. Muitos projetos adotam um pull request por commit, então se houver a necessidade de grande alteração de código, quebrar em commits menores (separando por lógica) facilita para quem vai revisar e aumenta as chances de ser aceito.

Após a inserção do novo código, deve ser feita a sequência para aplicar tais mudanças.

Adicionar o(s) arquivo(s) modificado(s) (Add), Commit com mensagem que sintetize, de forma clara, a mudança.
Por último, é hora de enviar as alterações para o repo remoto (push).

gustavo@linux:~$ git add <arquivo(s) alterado(s)>

gustavo@linux:~$ git commit -m <Mensagem da mudança>

gustavo@linux:~$ git push origin <nome-da-nova-branch>

Já no GitHub, a alteração será reconhecida e irá trazer a opção de comparar e abrir o PR (pull request).

Para mais detalhes sobre o Pull Request.

Sincronizar o fork

Agora que já fez o pull request (e ele foi aceito! :D), sabendo que já curtiu a proposta do projeto, é interessante manter o fork sincronizado com as atualizações do repositório principal.

O primeiro passo é adicionar o repo principal, com um nome diferente do fork (após clonar o fork com git clone, o repositório remoto é nomeado de origin), é comum nomear como upstream.

gustavo@linux:~$ git remote add upstream <link-repo-principal>

Então, basta sincronizar o repo local/fork com o principal:

gustavo@linux:~$ git fetch upstream

E, por fim, fazer o merge entre as branchs:

gustavo@linux:~$ git merge upstream/<branch-principal>

É ISTO!

Dica

Já tá rolando a contagem regressiva para o hacktoberfest 2021.

Autor

Gustavo Dias A.

Referências

Gerando chave SSH - Github

Gustavo Dias Alexandre — Wed, 29 Sep 2021 22:42:10 +0000

Para vincular um repositório local (git) à um repositório remoto (github) sem a necessidade de fornecer as credenciais a cada atualização, é possível adicionar a máquina local via SSH.

Setup

Este tutorial é baseado no sistema operacional Linux.

Gerando chave SSH

No terminal, utilize o ssh-keygen para gerar uma chave pública com as credenciais desejadas.

gustavo@linux:~$ ssh-keygen -t rsa -b 4096 -C "seu_email@mail.com"

Será criada uma nova chave ssh, utilizando o email fornecido.

> Generating public/private rsa key pair.

Será exibida uma mensagem para definir um arquivo onde a chave será salva. Por padrão, o sistema define ~/.ssh/id_rsa como o local para o arquivo, basta pressionar enter.

> Enter a file in which to save the key (/home/you/.ssh/id_rsa): [Press enter]

O próximo passo é definir uma senha. Caso deseja não utilizar senha, basta deixar vazio e pressionar enter.

> Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

É possível checar, no próprio terminal ou em algum editor de texto, a chave criada.

gustavo@linux:~$ cat ~/.ssh/id_rsa.pub

Adicionando chave ao Github

Após a criação das chaves SSH, é hora de adicioná-las ao Github.

Na página de configurações

Vá para a sessão de "SSH and GPG Keys"

E, crie uma nova chave (New SSH key)

Basta definir um título, a sua escolha, copiar e colar a chave gerada na sessão anterior (~/.ssh/id_rsa_pub).

tip: É legal ter títulos que remetam de alguma forma à máquina que está sendo utilizada, e a sua finalidade (home, work...).

É isto

Por fim, se o processo foi executado corretamente, já deve ser possível fazer git pull e git push da máquina local para o repositório remoto.

Autor

Gustavo Dias A.

Referências

Useful plugins to VS Code

Gustavo Dias Alexandre — Wed, 29 Sep 2021 22:36:35 +0000

Some useful plugins/extensions for VSCode IDE.

Tip

To install the plugins quickly, launch VS Code Quick Open (Ctrl + P), paste the command and press Enter.

ext install <plugin>

Extensions

Generic

Beautify - HookyQR - Beautify code in place for VS Code.

ext install HookyQR.beautify

Code Runner - Jun Han - Run code snippet or code file for multiple languages.

ext install formulahendry.code-runner

CodeMetrics - Kiss Tamás - Computes complexity in TypeScript / JavaScript / Lua files.

ext install kisstkondoros.vscode-codemetrics

ESLint - Dirk Baeumer - Integrates ESLint JavaScript into VS Code.

ext install dbaeumer.vscode-eslint

GitLens - Eric Amodio - Supercharge the Git capabilities built into Visual Studio Code.

ext install eamodio.gitlens

vscode-icons - VSCode Icons Team - Icons for Visual Studio Code.

ext install vscode-icons-team.vscode-icons

For specific languages

Python

Jupyter - Microsoft - Jupyter notebook support, interactive programming and computing that supports Intellisense, debugging and more.

ext install ms-toolsai.jupyter

Pylance - Microsoft - A performant, feature-rich language server for Python in VS Code.

ext install  ms-python.vscode-pylance

Python - Microsoft - IntelliSense (Pylance), Linting, Debugging (multi-threaded, remote), Jupyter Notebooks, code formatting, refactoring, unit tests, and more.

ext install ms-python.python

SQL

SQLite - alexcvzz - Explore and query SQLite databases.

ext install alexcvzz.vscode-sqlite

Markdown

markdownlint - David Anson - Markdown linting and style checking for Visual Studio Code.

ext install DavidAnson.vscode-markdownlint

Themes

Dracula Official - Dracula Theme - Official Dracula Theme. A dark theme for many editors, shells, and more.

ext install dracula-theme.theme-dracula

Omni Theme - RocketSeat - A dark theme made by Rocketseat.

ext install rocketseat.theme-omni

Author

Gustavo Dias A.