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 Git. Comparaçã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.
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.
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 voltaste ao teu repositório após muitas semanas ou meses, algumas das folhas de personagem ou scripts de Mod (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ão é necessário criar outra bifurcação, nem necessitas de clonar o teu repositório novamente. 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. Isto irá obter todas as atualizações que outras pessoas fizeram nos repositórios roll20 desde a última vez que os sincronizaste (incluindo uma série de folhas de personagem ou scripts de Mod (API) que possas não te importar). Este link tem um guia de sincronização do teu 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
Recomenda-se criar um novo ramo para cada projeto separado (folha de personagem ou script de Mod (API)) e para cada atualização separada. Por exemplo, se vais atualizar dois scripts de Mod (API) diferentes ao mesmo tempo, cria um ramo 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.
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 a criação de uma nova pasta para a tua folha de personagem ou script de Mod (API) e adicionar o código fonte a ele, ou fazer modificações nos arquivos 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 submissões de folhas de personagem, lembra-te de incluir sheet.json
e uma imagem de pré-visualização – consulta o readme para mais informações. Para submissões de scripts de Mod (API), lembra-te de incluir script.json
– consulta o readme para mais informações. Assumindo que tudo está correto, a sua folha ou script deve ser adicionada ao ficheiroapproved.yaml
e 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.
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
- Dicas sobre como usar o Github (tópico do fórum Roll20)
- O Fluxo de Trabalho do GitHub (visualização) (não é o fluxo que usamos, mas uma boa visualização) e Fluxo de Trabalho de Forking (o que usamos)
- Git - O guia simples (ferramenta de linha de comando) por Roger Dudler
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)
- 1.2 Branches12 min
Git e Github para poetas (para além do básico)
- 1.4 Problemas do GitHub12 min
- 1.10 Git Remotes14 min