Guia Iniciante para o GitHub

Este documento é um guia simples e básico para levar você de "O que é o Git no mundo?" para "Todo mundo deve usar minha nova ficha de personagem!" o mais rápido possível, sem tentar ensinar todas as complexidades que o sistema é capaz. O Git é um software de controle de versão, mas este guia irá ignorar completamente como você pode usá-lo para rastrear suas alterações e se concentrar apenas em mover suas atualizações para os repositórios principais do Roll20. A seção "Mais informações" contém links para guias sobre como o Git/GitHub funciona de forma geral.


O que é o Git/GitHub?

Git é um software que você instala localmente no seu computador que lida com o controle de versão para você. GitHub é um serviço de hospedagem para repositórios do Git. Então eles não são a mesma coisa: Git é a ferramenta, GitHub é o serviço para projetos que usam o GitComparação breve.

Existem várias maneiras diferentes de usar o Git. O Git é muito poderoso, mas para aproveitar ao máximo, você precisa aprender a usar o shell de comando (comic xkcd). A seção "Mais informações" na parte inferior tem leituras adicionais sobre o shell de comando para os interessados. No entanto, tudo o que este documento irá guiá-lo pode ser feito usando apenas a interface gráfica do GitHub Desktop (muito boa para manter o disco rígido do seu computador sincronizado com seu repositório - Veja "Clonar seu Repositório" abaixo) e as ferramentas web do GitHub, ambas são ferramentas simplificadas para usar o Git subjacente.


Configurar o GitHub

Criar sua conta

Para usar o GitHub, você precisa ter uma conta em seu site. Você pode criar uma conta paga ou uma conta gratuita. A menos que você planeje criar um grande número de projetos que não deseja compartilhar com o mundo, não há motivo para criar uma conta paga: a única diferença entre os vários níveis de preços é o número de repositórios privados que você pode ter. Todos, incluindo contas gratuitas, podem ter um número ilimitado de repositórios públicos.

Você estará lidando com os Repositórios principais do Roll20 para roll20-character-sheets e/ou roll20-api-scripts, que são repositórios públicos. Você também estará criando um fork desses repositórios, que também pode ser público, então para seus usos no Roll20, uma conta gratuita é tudo o que você precisa.


FAÇA UM FORK do Repositório Oficial do Roll20

Umforké uma cópia de um repositório. Fazer um fork de um repositório permite que você experimente livremente com alterações sem afetar o projeto original.
"roll20-character-sheets" é o repositório de Fichas de Personagem. Para Scripts de API, faça um fork de "roll20-api-scripts".

Fazer um fork é facilmente feito usando as ferramentas web do GitHub. Clique no botão Fork no repositório oficial localizado em https://github.com/Roll20/roll20-character-sheets  ou https://github.com/Roll20/roll20-api-scripts  conforme apropriado. Isso criará uma cópia desse repositório em sua conta, na qual você terá permissão para fazer alterações como desejar. Vocêpodebifurcar o repositório quantas vezes quiser, mas só precisa depara o bifurcar uma vez. Este novo repositório terá um endereço idêntico ao original, exceto que, em vez de estar na raiz "Roll20", terá uma raiz com o nome da sua conta Roll20.

Se você estiver trabalhando com outro usuário na mesma planilha ou script, pode ser uma boa ideia ir para as configurações do seu novo repositório e adicioná-lo como colaborador. Os detalhes de como adicionar um colaborador ou trabalhar com um colaborador estão além do escopo deste tutorial, no entanto.

Se você estiver familiarizado com o sistema de controle de versão Git, não precisará de nenhuma outra informação para concluir o envio da sua ficha de personagem. Todos os outros, continuem lendo!


CLONE Seu Repositório

Clonar um repositório também cria uma cópia, mas um repositório clonado é usado como uma cópia de trabalho e fica no disco rígido local do seu computador como pastas e arquivos normais. O Git mantém um link - por padrão chamado de "origin" - entre as pastas e o repositório de onde ele foi clonado.
A lista incluirá todos os repositórios em sua conta

Para o utilizador iniciante do Git, recomenda-se vivamente que descarregue e instaleGitHub para WindowsouGitHub para Mac, conforme apropriado para o seu sistema operativo. Estes serão doravante referidos neste documento como "GitHub Desktop" ou "o aplicativo desktop". Além de ser uma maneira simples de instalar e configurar o controle de versão Git em seu computador, as aplicações desktop do GitHub facilitam a vinculação à sua conta de usuário do GitHub. Ele irá informá-lo sempre que seus arquivos no seu computador estiverem desatualizados com o seu repositório no GitHub e permitirá que você sincronize os dois facilmente.

Quando você executar o aplicativo do GitHub pela primeira vez, ele solicitará que você faça login na sua conta do GitHub. Em seguida, clique no grande sinal de adição no canto superior esquerdo para clonar seu repositório. Ao clonar o repositório, você será solicitado a selecionar um local para colocar os arquivos. Certifique-se de selecionar um local que você possa encontrar facilmente, você precisará saber onde ele está! Se você adquirir um novo computador, a instalação do GitHub Desktop e a clonagem do seu repositório são as únicas etapas que precisam ser repetidas.

O aplicativo de desktop também possui a interface mais fácil para gerenciar Branches. Quando você troca de branches dentro do aplicativo de desktop, ele adicionará / removerá / alterará arquivos para que eles correspondam ao último commit feito na branch para a qual você mudou.

Se você não está usando o aplicativo GitHub, você pode encontrar a URL do clone para seu repositório na página do seu repo. O GitHub oferece tanto URLs de clone SSH quanto HTTPS, bem como uma URL de checkout do Subversion. Os detalhes de clonar seu repo manualmente estão além do escopo deste guia, no entanto. 


Fluxo de trabalho de Forking do GitHub

A configuração acima é feita apenas uma vez. A seção a seguir descreve os procedimentos que são recomendados a serem seguidos cada vez que você deseja enviar uma atualização para o Roll20.


Sincronize seus arquivos com o Roll20

Se você acabou de fazer o fork e clonar seu repositório há alguns minutos, ele ainda está sincronizado. Mas se você está voltando para o seu repositório após várias semanas ou meses, algumas das fichas de personagem ou scripts da API terão sido atualizados. Existe a possibilidade de que aquele que você deseja modificar esteja entre eles. Nesse caso, você precisa garantir que esteja trabalhando com a versão mais recente dos arquivos que você irá modificar. Nãoprecisa de criar outra bifurcação, nem precisa de clonar novamente o seu repositório. Você precisará atualizar seu fork com o master. Leia o guia abaixo sobre como sincronizar

Em vez de sincronizar, seja necessário ou não, você pode primeiro verificar se precisa sincronizar o(s) projeto(s) em que você estará trabalhando. Uma verificação fácil é olhar os arquivos no repositório Roll20 e verificar a data da última modificação. Outra opção é abrir os ficheiros e executar um utilitário"diff"sobre eles e a sua versão mais recente. Verifique se há algum pull request pendente nos arquivos que você irá atualizar. Se os arquivos específicos que você irá modificar não foram alterados desde a última vez que você sincronizou, realizar uma sincronização completa de tudo é opcional.

Outra opção é apenas puxar todas as atualizações do repositório master do Roll20. Isso pegará todas as atualizações que outras pessoas fizeram nos repositórios do roll20 desde a última vez que você os sincronizou (incluindo várias fichas de personagem ou scripts de API que você pode não se importar). Esta ligação temum guia para sincronizar o seu repositório com o Original. Quando terminar isso, os arquivos no repositório mestre do Roll20, seu próprio repositório e seu disco rígido devem estar todos iguais. Certifique-se também de atualizar sua campanha do roll20. 


Crie um Branch

É recomendado criar um novo branch para cada projeto separado (ficha de personagem ou script de API) e para cada atualização separada. Por exemplo, se você for atualizar dois scripts de API diferentes ao mesmo tempo, crie um branch para cada script. Se algumas semanas depois você decidir fazer alterações adicionais no mesmo script, crie um novo branch para a atualização mais recente. Como regra geral, crie um novo branch para cada solicitação de pull.

O aplicativo de desktop também possui a interface mais fácil para gerenciar Branches. No menu superior, basta selecionar "Branch / Novo branch". Quando você troca de branches dentro do aplicativo de desktop (a 2ª linha permite trocar o repositório em que você está trabalhando e trocar o branch atual), ele adiciona / remove / altera arquivos em seu disco rígido para que eles correspondam ao último commit feito no branch para o qual você mudou.

GitHub Compare.png


COMMIT as suas alterações e PUSH os seus commits

Quando fazcommit de alterações em, armazena um registo de tudo o que alterou, bem como uma descrição legível por humanos do que fez no seu computador local. 
Em seguida,pushos seus commits para o seu repositório.

Assim que tiver uma cópia funcional do seu repositório clonado, pode fazer-lhe alterações. Isto inclui criar uma nova pasta para a sua folha de personagem ou script API e adicionar o código fonte a ela, ou fazer modificações nos ficheiros já existentes.

Muitas pessoas, quando desenvolvem guiões ou fichas de personagens para o Roll20, fazem toda a edição num editor de texto (por exemplo, notepad++). Pode simplesmente abrir os ficheiros no seu disco rígido (os que foram criados no passo 'clonar') em qualquer editor de texto e fazer as alterações no editor. Sempre que quiser executar o código no Roll20, prima ctrl/a e ctrl/c para selecionar todo o texto e copiá-lo para a área de transferência. Em seguida, cole-o no campo correto da campanha do Roll20. Se forem necessárias alterações adicionais (por exemplo, depuração), é frequentemente mais fácil efetuar um ciclo contínuo de editar, copiar, colar e testar.

Quando você ordena ao editor de texto para salvar suas alterações, ele finalmente gravará suas alterações no arquivo que você estava editando, e o GitHub Desktop detectará que o arquivo que você editou foi alterado e exibirá o nome do arquivo que foi alterado em seu painel esquerdo e, no painel direito, exibirá um resumo do que ele detecta como sendo diferente entre o salvamento atual e o último commit feito. No entanto, essas alterações foram apenas detectadas, o GitHub não registrou efetivamente essas alterações até que você as cometa. Os especialistas em Git recomendam cometer com frequência, pois cometer dá a você um backup externo do seu trabalho e um registro de cada commit.

Você não pode cometer nenhuma alteração sem um Resumo, mas a Descrição é opcional.

Cometer é muito simples. O aplicativo desktop já fez todo o trabalho de identificar o que precisa ser comitado. Digite um título para as alterações eopcionalmenteinsira uma descrição mais longa, cometa a alteração pressionando o botão "cometer para (branch)". Certifique-se de fazer seus commits na sua branch de trabalho, não na sua branch master. Fazer commits frequentes fornece a você um histórico detalhado das alterações que você está fazendo, em oposição a um único commit com tudo uma vez que você terminar. Observe que há um limite de tamanho para o Resumo. No entanto, se você exceder o limite, sua mensagem irá automaticamente transbordar para a Descrição mais longa. Você pode ver isso acontecendo quando o texto no campo Resumo fica cinza.

Assim que você fizer o commit, o GitHub desktop deve exibir um aviso grande de que não há alterações locais. Ele também deve sugerir que você envie seu commit para a origem. Alternativamente, ele pode sugerir que você "Publique a Branch". Fazer o commit das suas alterações ainda as armazena apenas no seu computador. Para colocar essas alterações no GitHub, você precisa enviá-las para a origem, o repositório armazenado online. Basta pressionar o botão "Enviar para a Origem" ou "Publicar Branch". Alternativamente, a qualquer momento em que a origem e o clone estiverem desatualizados, deve haver um botão muito mal rotulado no canto superior direito com um número e uma seta. Isso deve, entre outras coisas boas, sincronizar tudo entre o seu repositório e o clone, para que você possa enviar isso em vez disso. No topo da ferramenta de desktop, o item do menu suspenso "Repositório - Push" também fará o trabalho.

Continue editando e fazendo commits até que suas alterações estejam completas e você tenha testado e depurado o código pronto para ser enviado para o restante do roll20 aproveitar. Agora você está pronto para solicitar que os administradores do site roll20 "puxem" suas alterações para o repositório oficial do roll20.


Crie uma solicitação de PULL

Como o nome sugere, umpull é o oposto de um push. Em vez de um repositório copiado enviando commits para o original, o original solicita commits da cópia.

Na página da web do seu repositório, há um botão verde que diz "Comparar, revisar, criar uma solicitação de pull" quando você passa o mouse sobre ele. Este botão irá levá-lo para uma página onde você pode criar uma solicitação de pull. Se houver alguma diferença entre o seu repositório ("head") e a versão do repositório do Roll20 ("base"), elas serão exibidas aqui. (Observe que você pode alterar o que usar como cabeça e base clicando no botão "Editar" próximo.) Como suas alterações estão todas em seu branch de trabalho, não no branch principal, você deseja que sua solicitação de pull venha do seu branch de trabalho.

Como não tem permissões de colaborador no repositório do Roll20, não pode executar a ação de pull você mesmo, mas podepedir aoutra pessoa para executar o pull. Pressione o grande botão verde rotulado "Criar solicitação de pull" e uma solicitação de pull será aberta no repositório base. As pessoas com permissão para fazê-lo (ou seja, os desenvolvedores do Roll20) podem examinar a solicitação de pull, bem como o conteúdo das alterações propostas, e então mesclar a solicitação no repositório oficial.

Para maior clareza, inclua o nome da ficha para a qual você fez alterações na solicitação de pull, por exemplo. "[Dungeondivers 3rd Edition] consertou a rolagem de Poder".

Para submeter fichas de personagem, lembre-se de incluirsheet.jsone uma imagem de pré-visualização - consulte oreadmepara mais informações. Para envios de scripts de API, lembre-se de incluirscript.json- consulte oreadmepara obter mais informações. Assumindo que tudo está correto, a sua folha ou script deve ser adicionada ao ficheiroapproved.yamle estar disponível para todos os utilizadores!

Uma vez por semana, o Roll20 processa todas as solicitações de planilha disponíveis. Quando isso ocorre, você receberá um e-mail do GitHub. Este e-mail informará se um comentário foi deixado em sua solicitação sobre um problema descoberto em sua submissão OU se sua planilha foi mesclada como esperado e sua solicitação foi fechada (porque foi concluída com sucesso).

Fazendo alterações em sua solicitação de PULL

Se você criar uma solicitação de pull e depois cometer & push algumas alterações adicionais em seu repositório/branch antes que a Pull Request seja mesclada, essas novas alterações serão automaticamente atualizadas/incluídas na solicitação de pull original; não há necessidade de fazer uma segunda solicitação.

Pull request button.png


Limpeza

NÃO exclua nenhum branch até que todas as solicitações de pull desse branch sejam concluídas e fechadas. Na verdade, não há pressa para excluir um branch. Eles não causam nenhum problema, desde que você se lembre de usar cada branch apenas uma vez.

O software do GitHub recomendará que você faça o Merge do seu Branch de volta para o master. Este é um passo necessário com outros fluxos de trabalho, mas não no Fluxo de Trabalho de Forking que estamos usando. Em vez disso, recomendamos sincronizar seu fork com o roll20 original como o primeiro passo na preparação para sua próxima atualização. Isso trará as atualizações que você acabou de fazer (bem como quaisquer alterações feitas por outras pessoas) para o seu fork.

Portanto, não há limpeza a ser feita.


Mais informações


Git e Github para Poetas Tutorial do Youtube

Vídeos de 10 a 20 minutos para pessoas não técnicas que ensinam o básico do Git e Github, mostrando como trabalhar com o Github no navegador, mas também têm uma introdução ao uso da linha de comando. Foi feito em 2016, mas não parece estar datado em uma olhada rápida (Março de 2019)


Git e Github para poetas (para além do básico)

 
Este artigo foi útil?
Utilizadores que acharam útil: 10 de 13