Contribuir com os documentos

Observação: para contribuir, você deve ter uma conta GitHub.

Editar um documento existente

  1. Localize o documento que você deseja editar.

  2. Selecione Contribuir para esse tópico

    Isso redirecionará automaticamente você para o arquivo de redução no GitHub associado com esse arquivo.

    Verifique se você está conectado ao GitHub. Se não, entre ou crie uma conta GitHub.

  3. Selecione o ícone de edição para editar com o editor do navegador.

  4. Fazer alterações embutidas.

    Ações possíveis:

    1. Editar arquivo
    2. Visualizar alterações
    3. Renomear o arquivo (é muito improvável que você queira fazer isso)

  5. Propor suas alterações como uma solicitação pull

  6. Examinar as alterações

    O que estamos procurando em uma solicitação pull

    • A alteração está correta — ela representa corretamente a tecnologia
    • Ortografia/gramática estão corretas
    • Local lógico na documentação

  7. Criar uma solicitação pull

Solicitações pull

A maioria das alterações será confirmada por meio da solicitação pull. Uma solicitação pull é uma maneira de analisar um conjunto de alterações com vários revisores, alterando e comentando sobre o conteúdo atual.

Dividir o repositório e editar localmente

Para o trabalho em documento de longo prazo, clone o repositório localmente e trabalhe em seu computador.

O guia a seguir mostra como emular minha (Sarah Cooley) configuração. Há muitas configurações alternativas que funcionam igualmente bem.

Observação: todas essas ferramentas de documentos funcionam igualmente bem no Linux/OSX. Se você quiser que outros guias, solicite.

Esse é dividido em três seções:

Configurar o git

  1. Instale o git (no Windows) aqui

    Há apenas um valor na instalação que você precisa alterar:

    Ajustando seu ambiente PATH Use Git no Prompt de Comando do Windows

    Isso permite usar comandos do git no console do PowerShell/em qualquer console do Windows.

  2. Configure sua identidade do git

    Abra uma janela do PowerShell e execute:

    git config --global user.name "User Name"
    git config --global user.email username@microsoft.com
    

    O git usa esses valores para rotular as confirmações.

    Caso receba o erro a seguir, provavelmente o Git não está instalado corretamente ou você precisa reiniciar o PowerShell.

    git : The term 'git' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
    
  3. Configure seu ambiente do git

    Configure um auxiliar de credencial para que você precise inserir apenas o nome de usuário e senha uma vez (pelo menos neste computador). Eu uso este auxiliar de credenciais do Windows básico

    Após a instalação, execute o seguinte para habilitar o auxiliar de credenciais e definir seu comportamento de push:

    git config --global credential.helper manager
    git config --global push.default simple
    

    Na primeira vez que você precisar realizar a autenticação no GitHub, será solicitado seu nome de usuário e o código de autenticação de dois fatores se ele estiver habilitado. Exemplo:

    C:\Users\plang\Source\Repos\Virtualization-Documentation [master]> git pull
    Please enter your GitHub credentials for https://github.com/
    username: plang@microsoft.com
    password:
    authcode (app): 562689
    

    Isso será automaticamente um Token de Acesso Pessoal com as permissões corretas no GitHub, em seguida, armazene esse token com segurança no computador local. Você não deve ser solicitado novamente no futuro.

  4. Divida o repositório

  5. Clone o repositório

    Git clone faz uma cópia local do repositório git com os ganchos certos para sincronizar com outros clones do mesmo repositório.

    Por padrão, o clone criará uma pasta com o mesmo nome do repositório no diretório atual. Mantenho todos os meus repositórios git no meu diretório de usuário. Leia mais sobre o git clone aqui.

    cd ~
    git clone https://github.com/Microsoft/Virtualization-Documentation.git
    

    Se for bem-sucedido, você agora terá uma pasta Virtualization-Documentation.

    cd Virtualization-Documentation
    
  6. [Opcional] Configurar o Posh-Git

    Posh-Git é um módulo do PowerShell criado pela comunidade que torna o uso do git no PowerShell um pouco mais amigável. Ele adiciona o preenchimento com Tab para o git no PowerShell e também pode fazer seu prompt exibir informações importantes sobre ramificação e estado do arquivo. Leia mais sobre isso aqui. Você pode instalar o Posh-Git executando o seguinte em um console do PowerShell de administrador.

    Install-Module -Name posh-git
    

    Para fazer Posh-Git funcionar automaticamente cada vez que você iniciar o PowerShell, adicione o seguinte código a seu perfil do PowerShell (por exemplo, %UserProfile%\My Documents\WindowsPowerShell\profile.ps1)

    Import-Module posh-git
    
    function global:prompt {
     $realLASTEXITCODE = $LASTEXITCODE
    
     Write-Host($pwd.ProviderPath) -nonewline
    
     Write-VcsStatus
    
     $global:LASTEXITCODE = $realLASTEXITCODE
     return "> "
    }
    

Validar e acumular as credenciais

Para validar se o repositório está configurado corretamente, tente extrair o conteúdo novo.

git pull

Configurar o ambiente de edição de markdown

  1. Baixe o VSCode

  2. Faça uma confirmação de teste. Se as credenciais forem armazenadas corretamente, ele deverá funcionar perfeitamente.