ver lista de contribuidores

Git e GitHub

Se você não sabe ou não está acostumado a usar essas ferramentas, pule para o passo a passo detalhado

Se você não configurou o Git veja como fazer isso clicando aqui .

Passo a passo simplificado

1. Após o fork e o clone, referencie o repositório oficial

git remote add upstream git@github.com:cypherpunksbr/cypherpunks.com.br.git

2. Crie uma branch para fazer suas alterações (crie com um nome coerente com o que vai ser feito)

git checkout -b nome_da_branch

3. Após as alterações, faça um commit com uma mensagem coerente do que foi feito

git add --all
git commit -am "sua mensagem"
git push origin nome_da_branch

4. Envie um Pull Request com as alterações feitas. Sua contribuição será analisada pela comunidade. Em alguns casos pediremos algumas alterações antes de dar merge.

5. Após o merge

* Delete a branch utilizada

git checkout main
git push origin :nome_da_branch
git branch -D nome_da_branch

* Atualize seu repositório com o repositório oficial:

git fetch upstream
git rebase upstream/main
git push -f origin main

6. Quando iniciar uma nova contribuição, inicie o processo pelo passo #2.

7. Importante

• Antes de enviar sua contribuição, certifique-se de que está enviando apenas um único commit que represente o que foi feito. Caso tenha feito vários commits, esmague-os antes de fazer o Pull Request.
• Caso tenha qualquer tipo de dúvida, abra uma Issue que faremos o possível para te ajudar.

Volte a página de contribuições e veja o restante das recomendações.

Passo a passo detalhado

Atenção! Antes de iniciar o passo a passo, leia toda a explicação até o fim e garanta que entendeu tudo o que tem que fazer.

I - Forkando o repositório

A primeira coisa a fazer é forkar o repositório. Acesse a página do repositório no Github e clique no botão Fork:

O que significa forkar? A tradução literal de fork é garfo. Então, você dá uma “garfada” no repositório, dá aquela enrolada no garfo e traz ele pra sua conta 😆

Quando você forkar o repositório, repare que, abaixo do nome do repositório é mostrado o repositório original, ou seja, de onde ele foi forkado:

Você agora pode fazer o que quiser com esse repositório (tomando cuidado com a licença sob a qual ele foi liberado). A ideia aqui é resolver um problema e enviar o pull request com a correção para o repositório original. Como você não tem permissão para commitar diretamente no repositório principal, você precisa forkar e alterar no seu, para então submeter a correção.

Após forkar, vamos fazer nossas alterações!

II - Clonando o repositório

Agora você precisa baixar os arquivos do repositório para que você possa alterar. A primeira coisa a fazer é copiar a URL do repositório daqui:

Confira se o texto destacado está como Clone with SSH. Se não estiver, clique em Use SSH que aparece ao lado.

Após copiar a URL, abra seu terminal, crie um diretório onde você vai guardar o projeto e digite git clone <url-do-repositorio>:

git clone git@github.com:jeffesonjp/cypherpunks.com.br.git

Neste momento você deve clonar o seu fork e não o repositório oficial. O comando git clone pega o repositório como ele está no GitHub, já iniciado e com todo o histórico de commits atualizado. Seria o mesmo que você executar os comandos:

git init
git remote add origin git@github.com:jeffesonjp/cypherpunks.com.br.git
git pull origin main

Pronto! Já temos nosso projeto clonado em nossa máquina local! Com esse comando (git clone), será criado um diretório com o mesmo nome do repositório. Entrando nele (cd cypherpunks.com.br), vamos começar a modificar!

III - Criando a branch para criar ou modificar algo

Agora vamos criar uma nova branch para a nossa tarefa. Digamos que vamos criar uma feature. Vamos criar uma branch com um nome que diga o que será feito. Antes de tudo, garanta que você está na branch main, executando o comando:

git branch

A resposta deve ser:

* main

Porque precisa estar na main? Por convenção, o git utiliza a branch main como padrão, para o código estável do projeto. Então, tudo o que estiver nessa branch, em qualquer repositório, – teóricamente – é código estável. Logo, você nunca irá mexer diretamente nela, mas em outras branchs, para então fazer merge com a main.

Agora vamos criar a branch com nossa modificação. Temos duas formas de fazer isso. A forma mais rápida é:

git checkout -b Atualiza_glossario

Atualiza_glossario é o nome da nossa branch. A outra forma de criar uma branch é com os comandos:

git branch Atualiza_glossario
git checkout Atualiza_glossario

O primeiro comando cria a branch. O segundo comando troca da branch main para a branch Atualiza_glossario

Mas o primeiro comando que executamos (git checkout -b Atualiza_glossario), já faz essas duas coisas em um comando só: cria a branch (-b) e já muda para a branch criada (git checkout).

Tá, mas porque eu preciso criar uma nova branch? Se tudo irá para a main, porque não posso modificar direto ali? Como eu disse, a branch main é a branch com o código final do projeto, estável. Criando uma nova branch, se você submeter o pull request para o repositório original, mas ele não for aceito, as alterações não estarão na sua branch main. Dessa forma, se você quiser manter sempre os dois repositórios atualizados e sincronizados, você só precisa apagar a branch que você criou e fez a feature. As duas main vão continuar iguaizinhas 😄

4. Após fazer sua alteração, é hora de enviar para o seu fork. Primeiro você precisa commitar sua alteração:

git add --all
git commit -am "Adiciona a expressão 'blind signature' ao glossario"

O commit não precisa ser nada muito formal, mas escreva de uma forma que qualquer pessoa que ler, entenda.

IV - Pull Request

Após commitar, nossa alteração já está na árvore do git. Vamos agora subir para o nosso repositório forkado:

git push origin Atualiza_glossario

Você vai rodar esse comando, trocando Atualiza_glossario pelo nome da sua branch, obviamente.

Fazendo isso, acesse a conta do repositório original no Github, e você verá uma mensagem como essa:

Depois é só clicar no botão verde Compare & pull request.

O que é Pull Request? Pull Request é quando você envia uma sugestão de melhoria para o repositório.

Quando você quer trazer, pegar, puxar algo para o seu repositório usando o git, você usa o comando git pull. Então, um pull request nada mais é do que uma requisição ou pedido para que aquele repositório faça um pull com as suas alterações. 😄

Após clicar no botão Compare & pull request, você será direcionado para a tela onde você vai criar o pull request e pode conferir se as alterações que aparecem realmente correspondem às alterações que você fez:

Na imagem acima você pode ver:

• Onde diz base fork é o diretório padrão. No meu caso, está em cypherpunksbr/cypherpunks.com.br.
• Ao lado, a branch para a qual eu vou enviar meu pull request. Vou enviar direto para a main do repositório padrão.
• head fork é o seu repositório, que você forkou. Na imagem, é o jeffesonjp/cypherpunks.com.br.
• E por fim, a branch onde eu fiz a alteração: Atualiza_glossario

Depois disso, você vai colocar um título no seu pull request, para que, ao visualizar a listagem de pull requests, fique fácil saber do que se trata. Normalmente, quando você só tem uma mensagem de commit, esse título é assumido com a mensagem. Ajuste conforme a necessidade.

Lembre-se de comentar porque você está fazendo esse pull request e porque faz sentido para o repositório. Uma boa defesa pode ajudar a fazer com que seu pull request seja aceito.

Antes de clicar no botão Create pull request, confira os dados da imagem abaixo:

Rolando um pouco, você vai ver os commits que você fez. Confira se está na branch correta, e que você está enviando somente aquilo que você alterou. Se você escolher uma branch errada para enviar, você verá milhares de outras alterações - ou talvez nenhuma, se for a mesma branch - que não fará sentido de ser feito o merge do pull request.

No meu caso, eu fiz só uma alteração no GLOSSARIO.md, adicionando a expressão “Blind signature - assinatura disfarçada ou oculta”.

Depois de tudo verificado, clique no botão Creat pull request e aguarde a resposta! Você será avisado por e-mail - se você não desabilitou as notificações - se houver qualquer atividade nesse pull request. Se a branch for fechada, foi por que o autor achou que a alteração não fez sentido ou o merge foi feito.

Se ele fez o merge, então sua alteração já faz parte do repositório principal, e você aparecerá na guia Contributors do repositório principal: Como você viu na imagem acima, aparece quantos commits você fez, quanto código você adicionou e quanto você removeu!

V - Modificações aprovadas

Caso o autor do repositório tenha aprovado sua branch e feito merge, siga os seguintes passos:

git checkout main
git push origin :Atualiza_glossario
git branch -D Atualiza_glossario

Como você bem se lembra, o primeiro comando (git checkout main) muda para a branch main. O segundo comando (git push origin :Atualiza_glossario) envia uma instrução para deletar a branch Atualiza_glossario do repositório da sua conta do GitHub. Enfim, o terceiro comando deleta a branch do seu repositório local.

Mas por que eu deveria apagar minhas branchs, não seria mais fácil eu simplesmente dar merge no meu repositório local e no GitHub? Você pode fazer isso, mas se houver outros commit aprovados antes do seu, você terá que atualizar o repositório com o oficial depois da mesma forma. Estamos sugerindo apenas que você atualize tudo de uma vez 😄

O próximo passo atualizará seu repositorio, tanto remoto quanto localmente.

VI - Manter o projeto sempre atualizado

Como atualizar seu repositório com o repositório oficial? O seu repositório forkado normalmente é adicionado como origin quando você faz o clone. Para sincronizar com o repositório principal, adicione esse repositório com outro nome (no nosso caso, upstream que é o nome do meu remote, poderia ser outro nome).

git remote add upstream git@github.com:cypherpunksbr/cypherpunks.com.br.git

É importante que você execute este comando logo após clonar o repositório para sua máquina. Este serve para dizer ao seu repositório local qual é a origem do repositório e servirá para manter seu fork atualizado de acordo com o repositório oficial. Se você apagar (por acidente, por exemplo) seu repositório local e clonar de novo, execute o mesmo comando.

Após isso faça o seguinte:

git fetch upstream
git rebase upstream/main
git push -f origin main

O comando git fetch upstream pega os dados do repositório remoto que nomeamos como upstream, no nosso caso é o git@github.com:cypherpunksbr/cypherpunks.com.br.git. O comando git rebase upstream/main rescreve o seu branch main de forma que os seus commits, que não estão no projeto original, apareçam e os deixem no topo da lista.

Se você não quiser reescrever o histórico do seu branch main (talvez porque alguém já o tenha clonado) então você deve substituir o último comando por um git merge upstream/main. No entanto, para fazer com que futuros pull requests fiquem o mais limpos possível, é uma boa ideia fazer o rebase.

Se você fez o rebase do seu branch a partir de upstream/main, recomendamos você a forçar um push para o seu próprio repositório do Github. Você pode fazer isso com git push -f origin main.

Quando iniciar uma nova contribuição comece pelo passo a partir da criação da branch.

Se você entendeu toda a explicação, volte ao começo do texto e faça o passo a passo simplificado .