Git para escritores de documentação

Alguns aspirantes a contribuidores da documentação podem não saber como usar o Git de forma eficaz para contribuir com a documentação do Fedora. Este documento tenta fornecer alguma orientação. Pretende ser opinativo para não sobrecarregar o leitor.

Este é um caminho, não o único. As instruções neste documento não são a única maneira de atingir os objetivos. Em alguns casos, podem nem ser a melhor maneira, mas são uma maneira que funciona. Isso é direcionado explicitamente a usuários git iniciantes e, portanto, não inclui muitas escolhas ou opções. À medida que você se familiariza com o git, pode se desviar de maneiras que funcionem melhor para você.

Pré-requisitos

Para fazer qualquer outra coisa nesta página, você vai querer o seguinte:

  • Uma conta no Fedora Account System (FAS)

  • git (dnf install git)

  • O editor de texto de sua escolha

  • Experiência básica de terminal

  • (recomendado) Podman (dnf install podman)

Embora este documento tenha sido escrito com o Fedora em mente, os passos abaixo funcionam em qualquer sistema operacional com o git instalado. Consulte a documentação do git para obter mais informações sobre a instalação do git em outros sistemas operacionais.

Antes de sua primeira edição

Ao começar, você não terá acesso de commit aos repositórios git para documentos. Você precisará criar sua própria cópia, chamada de "fork".

Você precisará manter seu fork atualizado com o repo oficial. Isso é abordado posteriormente neste documento.
Por padrão, git clone irá clonar um repositório em um subdiretório com o mesmo nome do repo que existe no diretório a partir do qual você executa o comando. A fim de manter seu sistema de arquivos limpo e organizado, você pode querer um diretório dedicado para manter todos os seus repositórios de documentos. Por exemplo: $HOME/fedora/docs
  1. Vá para o repositório upstream do Pagure

    1. Clique no menu suspenso '''Clone''' no Pagure

    2. Copie o conteúdo da caixa '''Git'''

    3. De um terminal, vá para o diretório em que deseja manter seu repositório. Por exemplo cd $HOME/fedora/docs. Você precisará criar este diretório se ele não existir (por exemplo: mkdir -p $HOME/fedora/docs)

    4. De um terminal, execute git clone <URL GIT> -o upstream. Por exemplo, git clone https://pagure.io/fedora-docs/quick-docs/ -o upstream.

  2. Crie seu fork do repositório do Pagure

    1. Vá ao repositório Pagure que você deseja criar um fork (por exemplo, https://pagure.io/fedora-docs/quick-docs/). Iremos nos referir a isso como o repositório ''upstream'' a partir de agora.

    2. Clique no botão '''Fork''' na parte superior.

    3. Clique no menu suspenso '''Clone''' no Pagure

    4. Copie o conteúdo da caixa '''SSH'''

  3. Adicione seu fork ao checkout local

    1. De um terminal, vá para o diretório que você clonou acima. (Por exemplo: cd $HOME/fedora/docs/quick-docs)

    2. Daquele diretório, execute git remote add origin <URL SSH>. (Por exemplo: git remote add origin ssh://git@pagure.io/forks/bcotton/fedora-docs/quick-docs.git)

Este documento usa o terminal para comandos git. No entanto, você também pode escolher usar uma ferramenta gráfica git. Os princípios do fluxo de trabalho são os mesmos.

Antes de toda contribuição

Antes de começar a fazer suas contribuições, você quer ter certeza de estar atualizado com o repositório upstream. Isso significa que você está fazendo alterações na versão mais recente.

  1. Certifique-se de que você está em seu branch master com git checkout master

  2. Obtenha as alterações do upstream com git pull

Isso assume que o repositório que você está editando usa master como o branch principal. Alguns repositórios podem ter um fluxo de trabalho diferente. Verifique com a equipe se não tiver certeza.
Se você usar a visualização da web do seu repositório fork, você desejará efetuar push do conteúdo atualizado para o seu fork. Faça isso com git push origin master.

Fazendo uma contribuição

É melhor criar um novo branch mesmo se você não precisar dele do que desejar mais tarde ter criado um branch porque está tentando resolver conflitos. Crie branches até mesmo para as contribuições mais triviais e você evitará aquele sofrimento potencial.

Agora é a hora de dar a contribuição que você veio dar aqui. Você vai querer começar criando um novo branch para fazer o trabalho.

  1. git checkout -b ''nome_de_branch'' (sendo ''nome_do_branch'' algo como issue8-fix_typos ou add_git_tips_for_writers)

Você pode nomear um branch como quiser. Nomes descritivos são bons, especialmente se for algo em que você trabalhará em várias sessões. Se você estiver trabalhando diretamente no repositório upstream, usar um nome de branch exclusivo e descritivo ajuda outros contribuidores a saberem qual é o seu branch.
Você pode verificar seu branch atual com git branch. Seu branch atual terá um * no início da linha. Se você precisar mudar para um branch existente, use git checkout ''nome_do_branch''.

Agora você pode fazer as alterações que desejar. Abra seu editor de texto favorito e edite. Quando terminar, é hora de fazer commit das alterações.

  1. git add ''arquivo(s) que você editou''

  2. git commit

  3. Edite a mensagem de commit e feche o editor. Se o seu sistema usa o vim como editor padrão (o que provavelmente usa, a menos que você o altere), digite i para entrar no modo de edição. Quando você terminar de escrever sua mensagem de commit, pressione a tecla Escape, digite :wq e pressione Enter.

Boas mensagens de commit são úteis quando alguém (incluindo você no futuro) olha o histórico de commits para ver o que foi feito. Uma boa mensagem de commit diz o que o commit faz e por quê.
Tente manter seus commits relacionados a uma única alteração lógica. Isso torna mais fácil desfazê-lo, se necessário. Uma "única alteração lógica" pode exigir a edição de vários arquivos, que devem estar todos em um commit, mas se você estiver adicionando conteúdo não relacionado, faça-o separadamente.

Finalmente, é hora de fazer push suas alterações de sua máquina local para o servidor remoto e criar a pull request.

  1. git push origin ''nome_do_branch''

  2. No seu navegador web, vá para seu repositório fork (por exemplo, https://pagure.io/fork/bcotton/fedora-docs/quick-docs)

  3. Siga as instruções específica de cada plataforma para a criação de uma pull request (documentação do Pagure e do GitHub)