14 KiB

Raw Permalink Blame History

AGENTS.md

Visão Geral do Projeto

Este é um repositório de currículo educacional para ensinar fundamentos de desenvolvimento web a iniciantes. O currículo é um curso abrangente de 12 semanas desenvolvido pelos Microsoft Cloud Advocates, com 24 aulas práticas que abordam JavaScript, CSS e HTML.

Componentes Principais

Conteúdo Educacional: 24 aulas estruturadas organizadas em módulos baseados em projetos
Projetos Práticos: Terrário, Jogo de Digitação, Extensão de Navegador, Jogo Espacial, Aplicativo Bancário, Editor de Código e Assistente de Chat com IA
Quizzes Interativos: 48 quizzes com 3 perguntas cada (avaliações pré/pós-aula)
Suporte Multilíngue: Traduções automáticas para mais de 50 idiomas via GitHub Actions
Tecnologias: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (para projetos de IA)

Arquitetura

Repositório educacional com estrutura baseada em aulas
Cada pasta de aula contém README, exemplos de código e soluções
Projetos independentes em diretórios separados (quiz-app, vários projetos de aula)
Sistema de tradução usando GitHub Actions (co-op-translator)
Documentação servida via Docsify e disponível em PDF

Comandos de Configuração

Este repositório é principalmente para consumo de conteúdo educacional. Para trabalhar com projetos específicos:

Configuração do Repositório Principal

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Configuração do Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint

API do Projeto Bancário (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

Projetos de Extensão de Navegador

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

Projetos de Jogo Espacial

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

Projeto de Chat (Backend em Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py

Fluxo de Trabalho de Desenvolvimento

Para Contribuidores de Conteúdo

Faça um fork do repositório na sua conta do GitHub
Clone o fork localmente
Crie uma nova branch para suas alterações
Faça alterações no conteúdo das aulas ou nos exemplos de código
Teste quaisquer alterações de código nos diretórios de projetos relevantes
Envie pull requests seguindo as diretrizes de contribuição

Para Estudantes

Faça um fork ou clone do repositório
Navegue pelos diretórios das aulas sequencialmente
Leia os arquivos README de cada aula
Complete os quizzes pré-aula em https://ff-quizzes.netlify.app/web/
Trabalhe nos exemplos de código nas pastas das aulas
Complete os exercícios e desafios
Faça os quizzes pós-aula

Desenvolvimento ao Vivo

Documentação: Execute docsify serve na raiz (porta 3000)
Quiz App: Execute npm run dev no diretório quiz-app
Projetos: Use a extensão Live Server do VS Code para projetos HTML
Projetos de API: Execute npm start nos diretórios de API correspondentes

Instruções de Teste

Teste do Quiz App

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

Teste da API Bancária

cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors

Abordagem Geral de Teste

Este é um repositório educacional sem testes automatizados abrangentes
O teste manual foca em:
- Exemplos de código executando sem erros
- Links na documentação funcionando corretamente
- Builds dos projetos concluindo com sucesso
- Exemplos seguindo boas práticas

Verificações Antes de Submissão

Execute npm run lint nos diretórios com package.json
Verifique se os links em markdown são válidos
Teste os exemplos de código no navegador ou Node.js
Certifique-se de que as traduções mantêm a estrutura adequada

Diretrizes de Estilo de Código

JavaScript

Use sintaxe moderna ES6+
Siga as configurações padrão do ESLint fornecidas nos projetos
Use nomes de variáveis e funções significativos para clareza educacional
Adicione comentários explicando conceitos para os alunos
Formate usando Prettier onde configurado

HTML/CSS

Elementos semânticos do HTML5
Princípios de design responsivo
Convenções claras de nomenclatura de classes
Comentários explicando técnicas de CSS para os alunos

Python

Diretrizes de estilo PEP 8
Exemplos de código claros e educacionais
Dicas de tipo onde úteis para aprendizado

Documentação em Markdown

Hierarquia clara de títulos
Blocos de código com especificação de linguagem
Links para recursos adicionais
Capturas de tela e imagens em diretórios images/
Texto alternativo para imagens para acessibilidade

Organização de Arquivos

Aulas numeradas sequencialmente (1-getting-started-lessons, 2-js-basics, etc.)
Cada projeto tem diretórios solution/ e frequentemente start/ ou your-work/
Imagens armazenadas em pastas images/ específicas de cada aula
Traduções na estrutura translations/{language-code}/

Build e Implantação

Implantação do Quiz App (Azure Static Web Apps)

O quiz-app está configurado para implantação no Azure Static Web Apps:

cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main

Configuração do Azure Static Web Apps:

Localização do aplicativo: /quiz-app
Localização de saída: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Geração de PDF da Documentação

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

Documentação Docsify

npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000

Builds Específicos de Projetos

Cada diretório de projeto pode ter seu próprio processo de build:

Projetos Vue: npm run build cria pacotes de produção
Projetos estáticos: Sem etapa de build, sirva os arquivos diretamente

Diretrizes para Pull Requests

Formato do Título

Use títulos claros e descritivos indicando a área de alteração:

[Quiz-app] Adicionar novo quiz para aula X
[Lesson-3] Corrigir erro de digitação no projeto terrário
[Translation] Adicionar tradução para espanhol na aula 5
[Docs] Atualizar instruções de configuração

Verificações Necessárias

Antes de enviar um PR:

Qualidade do Código:
- Execute npm run lint nos diretórios de projeto afetados
- Corrija todos os erros e avisos de lint
Verificação de Build:
- Execute npm run build se aplicável
- Certifique-se de que não há erros de build
Validação de Links:
- Teste todos os links em markdown
- Verifique se as referências de imagens funcionam
Revisão de Conteúdo:
- Revise para corrigir erros de ortografia e gramática
- Certifique-se de que os exemplos de código estão corretos e educacionais
- Verifique se as traduções mantêm o significado original

Requisitos de Contribuição

Concorde com o Microsoft CLA (verificação automatizada no primeiro PR)
Siga o Código de Conduta de Código Aberto da Microsoft
Consulte CONTRIBUTING.md para diretrizes detalhadas
Referencie números de issues na descrição do PR, se aplicável

Processo de Revisão

PRs revisados por mantenedores e pela comunidade
Clareza educacional é priorizada
Exemplos de código devem seguir as melhores práticas atuais
Traduções revisadas para precisão e adequação cultural

Sistema de Tradução

Tradução Automática

Usa GitHub Actions com workflow co-op-translator
Traduções automáticas para mais de 50 idiomas
Arquivos fonte nos diretórios principais
Arquivos traduzidos em diretórios translations/{language-code}/

Adicionando Melhorias Manuais à Tradução

Localize o arquivo em translations/{language-code}/
Faça melhorias preservando a estrutura
Certifique-se de que os exemplos de código permanecem funcionais
Teste qualquer conteúdo de quiz localizado

Metadados de Tradução

Arquivos traduzidos incluem cabeçalho de metadados:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Depuração e Solução de Problemas

Problemas Comuns

Quiz app não inicia:

Verifique a versão do Node.js (recomendado v14+)
Exclua node_modules e package-lock.json, execute npm install novamente
Verifique conflitos de porta (padrão: Vite usa porta 5173)

Servidor de API não inicia:

Verifique se a versão do Node.js atende ao mínimo (node >=10)
Verifique se a porta já está em uso
Certifique-se de que todas as dependências estão instaladas com npm install

Extensão de navegador não carrega:

Verifique se o manifest.json está formatado corretamente
Verifique o console do navegador para erros
Siga as instruções específicas do navegador para instalação de extensões

Problemas no projeto de chat em Python:

Certifique-se de que o pacote OpenAI está instalado: pip install openai
Verifique se a variável de ambiente GITHUB_TOKEN está configurada
Verifique as permissões de acesso aos modelos do GitHub

Docsify não serve os documentos:

Instale docsify-cli globalmente: npm install -g docsify-cli
Execute a partir do diretório raiz do repositório
Verifique se docs/_sidebar.md existe

Dicas para Ambiente de Desenvolvimento

Use VS Code com a extensão Live Server para projetos HTML
Instale as extensões ESLint e Prettier para formatação consistente
Use as DevTools do navegador para depurar JavaScript
Para projetos Vue, instale a extensão Vue DevTools no navegador

Considerações de Desempenho

Grande número de arquivos traduzidos (50+ idiomas) significa clones completos grandes
Use clone superficial se estiver trabalhando apenas no conteúdo: git clone --depth 1
Exclua traduções das buscas ao trabalhar no conteúdo em inglês
Processos de build podem ser lentos na primeira execução (npm install, build do Vite)

Considerações de Segurança

Variáveis de Ambiente

Chaves de API nunca devem ser comprometidas no repositório
Use arquivos .env (já em .gitignore)
Documente as variáveis de ambiente necessárias nos READMEs dos projetos

Projetos em Python

Use ambientes virtuais: python -m venv venv
Mantenha as dependências atualizadas
Tokens do GitHub devem ter permissões mínimas necessárias

Acesso aos Modelos do GitHub

Tokens de Acesso Pessoal (PAT) são necessários para os Modelos do GitHub
Tokens devem ser armazenados como variáveis de ambiente
Nunca comprometa tokens ou credenciais

Notas Adicionais

Público-alvo

Iniciantes completos em desenvolvimento web
Estudantes e autodidatas
Professores usando o currículo em salas de aula
O conteúdo é projetado para acessibilidade e construção gradual de habilidades

Filosofia Educacional

Abordagem de aprendizado baseada em projetos
Verificações frequentes de conhecimento (quizzes)
Exercícios práticos de codificação
Exemplos de aplicação no mundo real
Foco nos fundamentos antes de frameworks

Manutenção do Repositório

Comunidade ativa de alunos e contribuidores
Atualizações regulares de dependências e conteúdo
Issues e discussões monitoradas pelos mantenedores
Atualizações de tradução automatizadas via GitHub Actions

Recursos Relacionados

Módulos do Microsoft Learn
Recursos do Student Hub
GitHub Copilot recomendado para alunos
Cursos adicionais: IA Generativa, Ciência de Dados, ML, currículos de IoT disponíveis

Trabalhando com Projetos Específicos

Para instruções detalhadas sobre projetos individuais, consulte os arquivos README em:

quiz-app/README.md - Aplicativo de quiz em Vue 3
7-bank-project/README.md - Aplicativo bancário com autenticação
5-browser-extension/README.md - Desenvolvimento de extensão de navegador
6-space-game/README.md - Desenvolvimento de jogo baseado em Canvas
9-chat-project/README.md - Projeto de assistente de chat com IA

Estrutura de Monorepo

Embora não seja um monorepo tradicional, este repositório contém vários projetos independentes:

Cada aula é autônoma
Projetos não compartilham dependências
Trabalhe em projetos individuais sem afetar outros
Clone o repositório inteiro para a experiência completa do currículo

Aviso Legal:
Este documento foi traduzido utilizando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.

14 KiB Raw Permalink Blame History