12 recursos incríveis do GitHub

Pela minha vida, não consigo pensar em nenhuma introdução, então...

Nº 1: Edição de código em GitHub.com

Vou começar com o que acho que todo mundo já sabe (embora eu pessoalmente não tivesse ideia disso há uma semana). Ao visualizar qualquer arquivo de texto no GitHub, em qualquer repositório, você pode ver um pequeno lápis no canto superior direito. Se você clicar nele, poderá editar este arquivo. Depois de concluído, clique em Propor alteração de arquivo e o GitHub criará um fork e um Pull Request. Incrível, não é? Ele mesmo cria o garfo! Não há necessidade de bifurcar e fazer upload do código para você mesmo, fazer alterações localmente e enviá-lo de volta ao GitHub com uma solicitação pull. Muito conveniente se você precisar fazer edições mínimas. não é exatamente uma solicitação pull real

#2 Inserindo imagens

As descrições dos problemas não se limitam apenas a comentários de texto. Você sabia que pode colar imagens diretamente da área de transferência? Quando colado, você verá que ele foi carregado (para a nuvem, sem dúvida) e transformado em marcação para exibir a imagem. Gracioso!

#3 Formatação de código

Se você precisar escrever um bloco de código, comece com três crases e o GitHub tentará adivinhar em qual linguagem de programação você está escrevendo. Mas se você estiver postando um trecho de código em uma linguagem de programação como Vue, Typescript ou JSX, poderá especificar explicitamente a linguagem para que o destaque da sintaxe esteja correto. Observe o ```jsx na primeira linha: ...garantindo a exibição correta do trecho de código: (A propósito, isso também se aplica ao Gist. Se você especificar uma extensão .jsf para um Gist, a sintaxe JSF será destacada). Aqui está uma lista de todas as sintaxes suportadas .

#4 Fechando problemas usando “palavras mágicas” em Pull Requests

Digamos que você crie uma solicitação pull que corrige o problema nº 234. Você pode inserir o texto "corrige o problema nº 234" na descrição da sua solicitação (ou em qualquer lugar em qualquer comentário da solicitação de alteração). Depois disso, mesclar a solicitação pull fechará “automaticamente” o problema. Legal, não é? Veja mais informações sobre isso na documentação .

#5 Link para comentários

Você já precisou criar um link para um comentário específico e não sabia como? Esses dias já se foram porque vou lhe contar um segredo: para criar um link para um comentário, basta clicar na data/hora ao lado do título. Olha, gaearon agora tem foto!

#6 Link do código

Então você deseja criar um link para uma linha específica de código. Neste caso, tente o seguinte: Clique no número da linha ao lado do código desejado no arquivo aberto. Uau, viu? A URL mudou, o número da linha agora está visível nela! Se você mantiver pressionada a tecla SHIFT e clicar em outro número de linha, pronto! – O URL mudará novamente e o intervalo de linhas será destacado. Este URL agora apontará para este arquivo e este intervalo de linhas. Mas espere, ele aponta para o tópico atual. E se o arquivo mudar? Você provavelmente precisará, neste caso, de um link permanente para o arquivo em seu estado atual. Sou muito preguiçoso, então tirei uma captura de tela de todas as opções acima: A propósito, sobre URLs...

#7 Usando URL do GitHub como linha de comando

A navegação pelo GitHub usando a IU é organizada de forma muito conveniente. Mas às vezes, para chegar a um local específico, é mais rápido apenas digitá-lo na URL. Por exemplo, se eu quiser ir para um branch em que estou trabalhando e ver como ele se compara ao master, posso simplesmente digitar /compare/branchname após o nome do repositório. Isso me levará para a página diff desse branch: Mas essas são diferenças do branch master, mas se eu trabalhei com o branch de integração antes, posso inserir /compare/integration-branch...my-branch na URL Para amantes de teclas de atalho: CTRL+L ou CMD+L move o cursor para a barra de URL (pelo menos nos navegadores Chrome e Firefox). Isso, combinado com o preenchimento automático do navegador, torna a navegação entre ramificações muito mais fácil. Dica profissional: use as setas para navegar pelas sugestões de preenchimento automático do Chrome e pressione SHIFT+DELETE para remover itens do histórico (por exemplo, após mesclar uma ramificação). (Não sei se seria mais fácil ler essas teclas de atalho se eu colocasse um espaço nelas, como SHIFT + DELETE. Mas tecnicamente “+” não faz parte delas, então não gosto dessa opção. É por causa de coisas assim eu não durmo à noite, Rhonda.)

#8 Crie listas de problemas

Você quer uma caixa de seleção na descrição do problema? E você quer que uma barra bacana como “2 de 5” apareça quando você visualiza um problema da lista? Sem problemas! Você pode criar caixas de seleção interativas usando a seguinte sintaxe:

• [ ] Largura da tela (inteiro)
• [x] Suporte ao trabalhador de serviço
• [x] Buscar suporte
• [] Suporte para flexbox CSS
• [] Elementos personalizados

Sintaxe: espaço, hífen, espaço, colchete de abertura, espaço (ou x), colchete de fechamento, espaço e algumas palavras. Depois disso, você pode marcar/desmarcar esses botões! Por alguma razão, isso me parece algum tipo de mágica técnica. Você pode marcar as caixas! E ao mesmo tempo o texto original muda! É assustador pensar no que eles vão inventar a seguir. Ah, e se esse problema estiver no painel do projeto, o progresso será exibido lá também: Se você não entende o que quero dizer com "painel do projeto" - leia abaixo. Apenas alguns centímetros abaixo nesta página.

Nº 9 Painéis de projeto no GitHub

Para grandes projetos sempre usei o Jira. E para meus projetos pessoais sempre usei o Trello. Eu realmente gosto dessas duas ferramentas. Quando soube há algumas semanas que o GitHub oferecia uma opção própria, direto na aba Projetos do repositório, achei que faria sentido duplicar o conjunto de tarefas com as quais já trabalho no Trello. Não há nada engraçado aqui. E agora a mesma coisa no projeto GitHub: Gradualmente, seus olhos se acostumarão com a imagem de baixo contraste Por uma questão de velocidade, adicionei todos os itens acima como notas, o que significa que não são problemas "reais" do GitHub. Mas o poder do gerenciamento de problemas no GitHub reside na sua integração com o resto do repositório - então provavelmente é melhor adicionar problemas existentes do repositório ao painel. Clique em Adicionar cartões no canto superior direito e encontre o que você gostaria de adicionar. É aqui que a sintaxe de pesquisa especial se torna útil : por exemplo, digite is:pr is:open e você pode arrastar qualquer Pull Request aberto para o painel, ou label:bug se precisar corrigir alguns bugs. Você também pode converter notas existentes em problemas. E finalmente, a partir do formulário do problema existente, adicione-o ao projeto no painel direito. Ele irá para a lista de triagem daquele painel do projeto, para que você possa escolher em qual coluna colocá-lo Quando a descrição de uma “tarefa” está no mesmo repositório que o código que implementa esta tarefa, é muito (muito) conveniente. Isso significa que daqui a muitos anos você será capaz de executar git culpa em uma linha de código e descobrir todo o problema que levou a essa linha, sem precisar rastrear tudo no Jira/Trello/em outro lugar.

Imperfeições

Nas últimas três semanas tenho experimentado fazer tudo no GitHub em vez do Jira (em um projeto pequeno, meio estilo Kanban) e adorei. Mas não consigo imaginar isso para um projeto Scrum onde a velocidade de desenvolvimento e similares precisem ser avaliadas e calculadas adequadamente. A boa notícia é que os projetos do GitHub têm tão poucos “recursos especiais” que mudar para outro sistema não levará muito tempo. Então experimente e veja o quanto você gosta. Não sei o quão importante isso é, mas ouvi falar do ZenHub e o abri pela primeira vez há 10 minutos. É essencialmente uma extensão do GitHub onde você pode avaliar problemas e criar “épicos” e dependências. Existem gráficos de velocidade de desenvolvimento e esgotamento; Parece que é uma coisa incrível. Leitura adicional: Documentação do GitHub sobre projetos.

#10 Gwiki

Para um conjunto de páginas não estruturadas – como a Wikipedia – o GitHub Wiki (que chamarei de Gwiki de agora em diante) é ótimo. Para um conjunto estruturado de páginas - por exemplo, como sua documentação - nem tanto. Não há como indicar que “esta página é filha daquela”; não existem coisas convenientes como os botões “Próxima seção” e “Seção anterior”. Hansel e Gretel definitivamente se perderiam aqui, porque também não há “migalhas de pão” (operadores especiais de depuração - aprox. trad.). (Nota do autor: Você já leu essa história? É simplesmente desumano. Dois jovens bandidos matam uma pobre velhinha faminta, queimando-a viva em seu próprio forno . E, claro, deixando uma bagunça completa para ninguém entender. Acho que é por isso os jovens hoje em dia são tão sensíveis como o inferno – histórias lidas para crianças na hora de dormir hoje em dia não são cruéis o suficiente!) Continuando – para experimentar o Gwiki de verdade, inseri algumas páginas do NodeJS como páginas wiki e, em seguida, criei uma página personalizada barra lateral para simular a estrutura real do site. Esta barra lateral está sempre lá, embora a página atual não esteja destacada. Os links terão que ser mantidos manualmente, mas no geral tudo funciona bem. Se quiser, você pode dar uma olhada : Isso dificilmente pode competir com algo como o GitBook (que é usado na documentação do Redux ) ou um site personalizado. Mas isso já representa uns bons 80% e está tudo certo no seu repositório. Eu sou apenas um fã disso. Eu sugiro que se você superou o tamanho do único arquivo README.md e precisa de várias páginas diferentes para manuais do usuário ou documentação mais detalhada, faz sentido ficar com o Gwiki. Se a falta de estrutura/navegação te incomoda, passe para outra coisa.

Nº 11 páginas do GitHub

Você já deve saber que as páginas do GitHub podem ser usadas para hospedar um site estático. E se você não sabia, então você sabe agora. Porém, esta seção é dedicada a um tema mais específico: usar Jekyll para criar um site. Em sua forma mais simples, GitHub Pages + Jekyll pode renderizar o arquivo README.md usando um tema bonito. Por exemplo, dê uma olhada na minha página leia-me em about-github : Se você clicar na guia de configurações deste site GitHub, habilite GitHub Pages e selecione o tema Jekyll... Então teremos uma página no estilo do tema Jekyll : Você pode então criar um site estático inteiro baseado principalmente em arquivos de marcação facilmente editáveis, essencialmente transformando o GitHub em um CMS. Embora eu realmente não tenha usado isso, é assim que os sites são construídos usando a estrutura Bootstrap usando React, então não há nada de terrível nisso. Observo que Ruby deve estar rodando na máquina local (os usuários do Windows trocarão olhares de compreensão aqui e seguirão o outro caminho, os usuários do macOS dirão: “Qual é o problema, aonde você está indo? Ruby é uma plataforma universal! Há também um GEMS sistema de gerenciamento de pacotes!”) (Também vale a pena notar que "conteúdo ou comportamento agressivo ou ameaçador" não é permitido nas páginas do GitHub, então você não poderá postar sua versão da história de João e Maria lá).

Minha opinião

Quanto mais eu olhava para a combinação GitHub Pages + Jekyll (para este artigo), mais eu achava que a ideia toda parecia estranha. A ideia de “fazer seu próprio site com o mínimo esforço” é ótima. Mas para trabalhar nisso você ainda precisa da versão atual na máquina local. E para algo tão “simples” existem muitos comandos de linha de comando. Folheei as sete páginas da seção Introdução e senti que a única coisa simples era eu . E eu ainda nem descobri a sintaxe simples da página principal ou o básico de um simples “mecanismo de modelagem baseado na linguagem Liquid”. Prefiro escrever um site sozinho! Para ser honesto, estou um pouco surpreso que o Facebook esteja usando isso para documentação do React, quando eles provavelmente poderiam construir suas páginas do sistema de ajuda usando React e pré-renderizar como arquivos HTML estáticos todos os dias . Tudo o que eles precisam fazer é encontrar uma maneira de receber os arquivos de marcação existentes como se fossem provenientes do CMS. E se...

Nº 12 Usando GitHub como CMS

Digamos que temos um site com algum texto, mas não queremos armazenar esse texto como marcação HTML. Em vez disso, gostaríamos de armazenar pedaços de texto em algum lugar que possa ser facilmente editado por usuários não desenvolvedores. De preferência com alguma opção de versionamento. Talvez até com algum tipo de processo de revisão por pares. Aqui está o que sugiro: use os arquivos de marcação armazenados no repositório para armazenar o texto. E use um componente no lado do cliente que recuperaria esses trechos de texto e os exibiria na página. Sou fã do React, então aqui está um exemplo de um componente <Markdown> adequado que, dado um caminho para um arquivo markdown, irá extraí-lo, analisá-lo e renderizá-lo como HTML.

class Markdown extends React.Component {
    constructor(props) {
      super(props);

      // Конечно, вам нужно заменить это на свой URL
      this.baseUrl = 'https://raw.githubusercontent.com/davidgilbertson/about-github/master/text-snippets';

      this.state = {
        markdown: '',
      };
    }

    componentDidMount() {
      fetch(`${this.baseUrl}/${this.props.url}`)
        .then(response => response.text())
        .then((markdown) => {
          this.setState({markdown});
        });
    }

    render() {
      return (
        <div dangerouslySetInnerHTML={{__html: marked(this.state.markdown)}} />
      );
    }
}

(Eu uso o pacote marcado como npm aqui para analisar a marcação em HTML) A URL aponta para meu repositório de exemplo, que contém arquivos de marcação no diretório /text-snippets . (Você também pode usar a API do GitHub para buscar content , mas duvido que precise disso.) Você poderia usar um componente como este:

const Page = () => (
  <div className="page">
    <div className="about-us">
      <Markdown url="about-us.md" />
    </div>

    <div className="disclaimer">
      <p>A very important disclaimer:</p>

      <Markdown url="disclaimers/home-page-disclaimer.md" />
    </div>
  </div>
);

Então agora o GitHub atua como, de certa forma, seu CMS para aqueles trechos de texto que você gostaria de hospedar. O exemplo acima só recupera a marcação depois que o componente é carregado no navegador. Se precisar de um site estático, você terá que renderizá-lo no servidor. Boas notícias! Não há nada que impeça você de recuperar todos os arquivos de marcação no servidor (usando qualquer estratégia de cache de sua preferência). Se você decidir seguir esse caminho, faz sentido usar a API GitHub para obter uma lista de todos os arquivos de marcação em um diretório. Bônus – utilitários GitHub! Já uso a extensão Octotree Chrome há algum tempo e recomendo-a a você. Não sem reservas, mas ainda assim recomendo. Ele exibe um painel à esquerda com uma visualização em árvore do repositório que você está navegando. E com esse vídeo aprendi sobre o octobox , que também me parece um utilitário muito bom até agora. Esta é a caixa de entrada para seus problemas do GitHub. Isso é tudo que você precisa saber sobre ele. Falando em cores, tirei todas as screenshots acima com um tema claro para não assustar. Mas se eu prefiro cores escuras em todo o resto, então por que tolerar o GitHub mortalmente pálido? Aqui usei uma combinação da extensão Stylish para o navegador Chrome (que pode aplicar temas a qualquer site) e o estilo GitHub Dark . E para começar, o tema escuro das ferramentas de desenvolvedor do GitHub (integrado, você só precisa habilitá-lo) e o tema Atom One Dark para Chrome.

Bitbucket

A rigor, não é totalmente apropriado aqui, mas não posso deixar de mencionar o Bitbucket. Há dois anos comecei um projeto e passei meio dia escolhendo a melhor hospedagem git. Portanto, o Bitbucket venceu por uma margem significativa. Seu pipeline de revisão de código está muito à frente da concorrência (isso foi muito antes do GitHub ter o conceito de revisor). Desde então, o GitHub também adquiriu análises. Infelizmente, não tive a chance de usar o Bitbucket no ano passado - talvez eles tenham avançado em alguma coisa novamente. Por isso recomendo que quem é responsável pela escolha de um serviço de hospedagem git também preste atenção ao Bitbucket.

Conclusão

Isso é tudo! Espero ter conseguido lhe contar pelo menos três coisas que antes você desconhecia. E também espero que você tenha se divertido lendo meu artigo.