Como contribuir

Agradecemos por melhorar o Awesome Copilot Adventures.

[!IMPORTANT] Comece com um resultado de aprendizagem e evidências observáveis, não com uma lista de funcionalidades ou uma história de fantasia.

Ciclo de contribuição

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
flowchart LR
    accTitle: Pontos de controle de evidências da contribuição
    accDescr: Uma contribuição parte de um resultado de aprendizagem e passa por fontes oficiais, definição de evidências, implementação, validação e revisão.
    O["Um resultado de aprendizagem"] --> D["Documentação oficial"]
    D --> E["Evidências e restauração"]
    E --> C["Aventura + laboratório + rubrica"]
    C --> V["Validação direcionada"]
    V --> P["Pull request pronto para revisão"]

Legenda. Os retângulos são etapas da contribuição. As setas contínuas mostram a ordem do trabalho que pode ser revisado.

Explicação. Defina o resultado de aprendizagem e suas evidências antes de escrever o exercício. A validação e a revisão são separadas da produção do artefato.

Antes de escrever

1. Escolha um objetivo principal de aprendizagem sobre desenvolvimento agêntico.
2. Verifique a terminologia e o comportamento na documentação oficial atual do GitHub ou da Microsoft.
3. Decida qual primitiva é necessária: instruções, prompt, skill, agente personalizado, MCP ou hook.
4. Defina evidências determinísticas, uma falha intencional e as etapas de restauração.
5. Identifique comportamentos estáveis, em versão prévia, experimentais ou dependentes de disponibilidade.

Lista de verificação da aventura

• Crie adventures/<level>/<slug>/README.md.
• Crie adventures/<level>/<slug>/rubric.md.
• Adicione um projeto inicial em labs/<slug>/ quando houver alterações em arquivos ou configurações.
• Adicione ou atualize o verificador determinístico.
• Referencie uma imagem de destaque em assets/images/adventures/.
• Adicione fontes oficiais e uma data real de last_verified.
• Inclua Ask → Plan → Agent → Revisão → Evidências.
• Inclua uma falha intencional e um desafio independente.
• Execute npm test.
• Execute a compilação ou o teste direcionado da linguagem, quando aplicável.

Não crie uma cópia separada exclusiva para Ask. Ask é um papel de investigação dentro da mesma aventura progressiva.

Estrutura da documentação

• Use títulos significativos e parágrafos concisos.
• Use GitHub Alerts para notas, avisos e cuidados importantes.
• Use Mermaid quando um processo, grafo de dependências ou sequência ficar mais claro visualmente.
• Mantenha os diagramas legíveis sem depender apenas de cores.
• Inclua texto alternativo para toda imagem significativa.
• Prefira links relativos dentro do repositório.
• Não coloque instruções essenciais apenas em uma imagem ou vídeo.
• Siga o padrão monocromático de diagramas em todos os blocos Mermaid, incluindo títulos acessíveis, legendas e explicações.
• Mantenha os laboratórios práticos como exercícios numerados, não como aventuras de fantasia. Para alterações, adicione uma entrada no catálogo, uma fixture local e um registro do resultado da auditoria.

Mídia

Use Prompts de mídia. As imagens de destaque geradas devem ter 1456×832, não conter texto incorporado e incluir texto alternativo significativo. Os vídeos precisam de uma imagem de capa e de uma alternativa com movimento reduzido.

Pull requests

Use um título específico, como New Copilot Adventure: The Skill Grimoire of Algora. Descreva:

• o objetivo de aprendizagem;
• as fontes oficiais e o status das funcionalidades;
• os arquivos e as alterações de comportamento;
• os comandos de validação e seus resultados;
• as limitações e as mídias a serem adicionadas posteriormente.