Como escrever seu primeiro tutorial da comunidade

Este espaço é dedicado aos usuários do Earth Engine que querem compartilhar conhecimento com o restante da comunidade. Criados por usuários do Earth Engine para usuários do Earth Engine, os tutoriais desta seção são destinados a todos os níveis, de iniciantes a usuários mais avançados.

Os tutoriais podem ser enviados como texto simples e código formatado usando a linguagem de marcação Markdown ou como blocos do Colab que contêm Markdown e código Python executável. Os tutoriais criados usando as bibliotecas de cliente JavaScript do Earth Engine geralmente são escritos em Markdown, enquanto o Colab é recomendado para tutoriais baseados nas bibliotecas de cliente Python do Earth Engine.

Antes de começar

Código de conduta

A equipe do Earth Engine tem o compromisso de promover uma comunidade inclusiva e sem assédio. Leia nosso Código de conduta antes de contribuir.

Como participar do GitHub

Os tutoriais da comunidade do Earth Engine são compartilhados e revisados pelo GitHub. Se você ainda não tiver uma conta do GitHub, crie uma em https://github.com/join.

Como propor um tutorial

Antes de investir muito tempo e esforço em um novo tutorial, os colaboradores em potencial precisam enviar uma proposta simples com algumas informações básicas. Isso permite que os autores trabalhem com os responsáveis pela manutenção da documentação do desenvolvedor do Earth Engine para concentrar os esforços em tutoriais que oferecem o maior valor à comunidade de usuários do Earth Engine. Também economiza tempo, evitando possíveis idas e vindas durante o processo de revisão.

Propor um tutorial

Primeira configuração

Se esta for a primeira vez que você envia um tutorial para o repositório do GitHub da comunidade do Earth Engine, conclua estas etapas antes de começar a trabalhar no tutorial:

  1. Aceite o Contrato de licença de colaborador (CLA, na sigla em inglês) em:

    https://cla.developers.google.com

  2. Leia e internalize o Guia de estilo de tutoriais da comunidade.

Como escrever e enviar um tutorial

Depois que a proposta de tutorial for aceita pelos responsáveis pela manutenção, haverá várias opções para editar o tutorial e enviá-lo ao repositório da comunidade do Earth Engine:

Início rápido do Markdown

Você pode bifurcar o repositório do GitHub e criar um novo tutorial diretamente via o site do GitHub para começar rapidamente sem ferramentas ou configurações adicionais:

  1. Faça login no GitHub, se ainda não tiver feito isso.

  2. Para criar e editar um novo arquivo de tutorial, clique em Novo tutorial. Você vai receber uma solicitação para bifurcar o repositório, se necessário.

    Novo tutorial

  3. Insira um nome para o arquivo de tutorial do formulário:

    your-tutorial-name/index.md

    Em que your-tutorial-name é o nome abreviado do tutorial em letras minúsculas. Use traços ("-") para separar palavras. Não use espaços ou qualquer outra pontuação no nome da pasta.

  4. Edite o tutorial diretamente no editor de arquivos do GitHub, usando "Visualizar" para verificar a saída formatada. Consulte também Editar arquivos no seu repositório na documentação do GitHub.

  5. Quando estiver tudo pronto, faça commit das mudanças e abra uma solicitação de pull.

notebook do Colab

Clique aqui para começar a escrever um tutorial no Colab:

Novo tutorial do Colab

Isso vai abrir um bloco de notas com instruções para criar e enviar o tutorial.

Avançado

Se você já estiver familiarizado com o GitHub, o Git e ferramentas relacionadas, o processo geral será o mesmo para enviar tutoriais do Markdown e do Colab tutoriais:

  1. Bifurque e clone o repositório do GitHub google/earthengine-community.

  2. Crie um diretório em tutorials com o nome abreviado do tutorial (por exemplo, tutorials/my-amazing-tutorial).

  3. Adicione o cabeçalho apropriado para Markdown ou Colab.

  4. Confirme o tutorial no novo diretório com o nome do arquivo index.md (para Markdown) ou tutorial.ipynb (para Colab). Confirme as imagens usadas no tutorial no mesmo diretório.

  5. Envie o novo conteúdo para sua bifurcação e abra uma solicitação de envio.

Ao criar uma solicitação de pull, consulte a proposta original pelo número de referência do GitHub na seção de comentários. Por exemplo, se o problema for #123, coloque o texto "Closes #123" na descrição da solicitação de pull para referenciar a proposta original e marcá-la automaticamente como concluída quando o tutorial for publicado.

Depois de abrir uma solicitação de pull, um ou mais responsáveis pela manutenção serão atribuídos para revisar o envio. O(s) revisor(es) vão trabalhar com você para garantir que o envio esteja completo, correto e consistente com o Guia de estilo de tutoriais da comunidade do Earth Engine.

Depois que a solicitação de pull for aprovada, o tutorial será publicado pelos responsáveis pela manutenção do repositório.