Git, documentação, publicação e apresentação

Identificação

• Duração: 2 horas
• Tipo: oficina de entrega
• Entrega: projeto versionado, documentado, publicado e apresentado
• Rubrica: ../materiais/rubrica-projeto-modulo-1.md
• Roteiro de apresentação: ../materiais/roteiro-apresentacao.md
• README de referência: ../exemplos/aula-1.2/README.md

Introdução

O que é Git?

Git é um sistema de controle de versão. Ele registra alterações nos arquivos de um projeto e permite consultar como o código evoluiu.

Com Git podemos:

• registrar uma versão do projeto;
• comparar mudanças;
• recuperar versões anteriores;
• criar linhas de trabalho separadas;
• identificar quando e por que algo mudou;
• colaborar sem substituir arquivos manualmente.

Todo Git é do GitHub?

Não. Git e GitHub são coisas diferentes.

Git -> ferramenta de controle de versão
GitHub -> serviço on-line que pode hospedar repositórios Git

GitHub utiliza Git, mas Git não depende do GitHub. Também existem outros serviços de hospedagem e servidores Git privados.

Consigo utilizar Git somente no meu computador?

Sim. Um repositório Git pode existir inteiramente no computador local:

git init
git add index.html
git commit -m "cria página inicial"

Esses comandos criam e registram versões localmente. Não é necessário possuir conta em um serviço on-line.

Quando conectamos um repositório local a outro repositório, chamamos o segundo de remoto. O remoto pode estar no GitHub, em outro serviço, em um servidor da empresa ou até em outra localização autorizada.

Git publica meu site?

Não automaticamente. Git controla versões. Publicação é o processo de colocar os arquivos em um servidor que possa ser acessado pelos usuários.

Algumas plataformas utilizam um repositório Git como origem de uma publicação:

Git registra o projeto
Serviço recebe o repositório
Fluxo automatizado publica os arquivos
Usuário acessa a URL

São etapas relacionadas, mas diferentes.

O que são documentação e apresentação?

Documentação explica como compreender, executar, testar e continuar o projeto. O README é normalmente o primeiro documento consultado.

Apresentação demonstra o problema, a solução, as decisões, os resultados e as limitações. Código sem documentação ou explicação pode funcionar, mas continua difícil de avaliar e manter.

Objetivos

Ao final da aula, o aluno deverá conseguir:

1. iniciar e organizar um repositório Git;
2. criar commits pequenos e compreensíveis;
3. proteger arquivos que não devem ser versionados;
4. escrever um README que permita executar e avaliar o projeto;
5. preparar a landing page para publicação;
6. executar uma verificação final;
7. publicar a aplicação em um servidor web;
8. apresentar o projeto com começo, meio e fim;
9. demonstrar acessibilidade, responsividade e tratamento de erros;
10. responder perguntas técnicas sobre suas decisões.

Pré-requisitos

• aulas 1.1 a 1.5 concluídas;
• landing page funcional;
• auditoria registrada;
• Git instalado;
• acesso a um terminal.

Pergunta orientadora

O que transforma uma pasta com arquivos em um projeto profissional que outra pessoa consegue avaliar, executar e continuar?

Roteiro sugerido

1. Entrega profissional

Uma entrega não é apenas uma página visual.

Ela deve conter:

• código organizado;
• histórico compreensível;
• instruções de execução;
• escopo;
• critérios atendidos;
• limitações conhecidas;
• evidências de teste;
• endereço publicado;
• capacidade de explicação.

O projeto precisa ser utilizável por alguém que não acompanhou sua construção.

2. Estrutura final

knowledge-ai/
|-- README.md
|-- .gitignore
|-- index.html
`-- assets/
    |-- fluxo-conhecimento.svg
    |-- main.js
    `-- styles.css

Não inclua:

• arquivos temporários;
• credenciais;
• senhas;
• tokens;
• cópias duplicadas;
• arquivos sem utilização;
• dados pessoais de teste.

3. Iniciando o Git

Dentro da pasta:

git init
git status

git status deve ser consultado antes e depois de cada commit.

Configuração de identidade

Se necessário:

git config user.name "Seu Nome"
git config user.email "voce@example.com"

Evite alterar configuração global em computadores compartilhados sem compreender o impacto.

4. .gitignore

Exemplo:

.env
.env.*
!.env.example
node_modules/
dist/
coverage/
*.log
tmp/

O .gitignore não remove automaticamente um arquivo que já foi versionado.

Antes do primeiro commit:

git status

Confirme cada arquivo listado.

5. Primeiro commit

git add index.html assets README.md .gitignore
git status
git commit -m "feat: cria landing page da Knowledge AI"

Não utilize automaticamente:

git add .

Primeiro inspecione o que será incluído.

6. Commits compreensíveis

Um bom commit:

• possui um objetivo;
• pode ser explicado;
• não mistura mudanças sem relação;
• utiliza mensagem curta e específica;
• deixa o projeto em estado válido.

Exemplos:

feat: adiciona formulário da lista de espera
style: cria layout responsivo da landing page
fix: preserva dados após falha simulada
docs: adiciona instruções de execução
test: registra auditoria do fluxo principal

Evite:

ajustes
teste
final
agora vai
alterações diversas

7. Leitura do histórico

git log --oneline
git show
git diff

Perguntas:

• o histórico conta a evolução do projeto?
• uma pessoa consegue encontrar a correção de um problema?
• existem arquivos sensíveis?
• algum commit reúne mudanças demais?

8. Branches

Para uma nova funcionalidade:

git switch -c feature/depoimento

Depois:

git status
git add caminho/do/arquivo
git commit -m "feat: adiciona depoimento à landing page"

Branches serão aprofundadas no Módulo 3. Nesta aula, o objetivo é compreender que trabalho novo pode ser isolado antes da integração.

9. README

O README responde:

1. o que é o projeto;
2. qual problema resolve;
3. como executar;
4. como utilizar;
5. quais tecnologias utiliza;
6. como foi testado;
7. quais são as limitações;
8. quais são os próximos passos.

Estrutura:

# Knowledge AI

## Sobre

## Funcionalidades

## Tecnologias

## Estrutura

## Como executar

## Como testar

## Acessibilidade

## Segurança e privacidade

## Limitações

## Próximos passos

Não descreva funcionalidades que não existem.

10. Capturas

Inclua:

• versão desktop;
• versão mobile;
• estado de sucesso;
• estado de erro, quando relevante.

Cuidados:

• utilize dados fictícios;
• não capture favoritos, abas ou informações privadas;
• use nomes de arquivo claros;
• comprima imagens sem comprometer a leitura;
• escreva textos alternativos quando as imagens forem incorporadas em uma página.

11. Preparação para publicação

Antes de publicar:

• confirme caminhos relativos;
• verifique diferenças entre letras maiúsculas e minúsculas;
• remova links locais do computador;
• remova dados de teste;
• confirme que nenhum segredo está no código;
• valide HTML, CSS e JavaScript;
• teste com servidor HTTP;
• execute a lista de verificação.

Um caminho que funciona no Windows pode falhar em um servidor que diferencia maiúsculas e minúsculas.

12. Servidor local

Abrir o HTML diretamente pode ter comportamento diferente de uma aplicação servida por HTTP.

Utilize um servidor web local. No ambiente do curso:

http://localhost/site/PosIA/

Confirme:

• status do documento;
• CSS carregado;
• JavaScript carregado;
• SVG carregado;
• ausência de erro no console.

13. Publicação

A aplicação estática pode ser publicada em:

• servidor web próprio;
• serviço de hospedagem estática;
• armazenamento com entrega web;
• plataforma de implantação conectada ao repositório.

O processo conceitual:

repositório -> compilação, se existir -> arquivos públicos -> servidor -> HTTPS

Nesta etapa não existe compilação. São publicados:

index.html
assets/

14. Configuração do caminho

Evite caminhos absolutos locais:

<!-- Não funciona para outros usuários -->
<script src="C:\meu-projeto\assets\main.js"></script>

Utilize:

<script type="module" src="assets/main.js"></script>

15. HTTPS

Uma aplicação pública deve utilizar HTTPS.

Após a publicação:

• confirme o cadeado do navegador;
• abra a página em janela privada;
• teste em outro dispositivo;
• verifique recursos bloqueados;
• repita o formulário.

16. Verificação final

Código

git status
git log --oneline

O diretório de trabalho deve estar no estado esperado.

Navegador

• HTML;
• CSS;
• JavaScript;
• SVG;
• console;
• rede;
• teclado;
• formulário;
• 320 px;
• desktop.

Conteúdo

• ortografia;
• títulos;
• links;
• contato;
• aviso de simulação;
• finalidade do projeto.

17. Apresentação

Uma apresentação de cinco a sete minutos:

1. problema;
2. público;
3. proposta;
4. demonstração;
5. decisões técnicas;
6. qualidade e segurança;
7. limitações;
8. próximos passos.

Não comece mostrando arquivos. Primeiro explique por que o produto existe.

18. Demonstração

Roteiro seguro:

1. abrir a página;
2. demonstrar responsividade;
3. navegar com teclado;
4. enviar dados fictícios válidos;
5. mostrar retorno;
6. provocar o erro com @erro.local;
7. mostrar preservação dos dados;
8. abrir DevTools;
9. apresentar console limpo;
10. mostrar o README.

Tenha capturas como contingência, mas priorize a demonstração ao vivo.

19. Defesa técnica

O aluno deve responder:

• por que utilizou HTML semântico?
• por que escolheu mobile first?
• quando usou Flexbox e Grid?
• por que o formulário escuta submit?
• por que utilizou textContent?
• o que a CSP protege e o que não protege?
• por que a validação precisa ser repetida no servidor?
• quais dados não devem ficar no front-end?
• qual seria a próxima evolução?

Uma boa resposta apresenta decisão, razão, alternativa e consequência.

20. Retorno

Ao receber retorno:

1. confirme o cenário;
2. reproduza;
3. registre;
4. classifique;
5. corrija;
6. teste novamente;
7. crie um commit específico.

Evite modificar o projeto durante a apresentação sem compreender o problema.

21. Laboratório guiado

Passo 1 - Limpeza

• remova arquivos não utilizados;
• revise caminhos;
• procure credenciais;
• revise dados fictícios.

Passo 2 - Git

• crie .gitignore;
• inspecione git status;
• organize commits.

Passo 3 - README

• copie a estrutura de referência;
• ajuste ao seu projeto;
• registre limitações reais.

Passo 4 - Auditoria

• execute a lista de verificação da Aula 1.5;
• corrija bloqueios;
• registre resultado.

Passo 5 - Publicação

• publique os arquivos;
• abra a URL pública;
• teste em outra sessão.

Passo 6 - Apresentação

• utilize o roteiro;
• cronometre;
• pratique respostas técnicas.

22. Exercício de fixação

Crie três commits separados:

1. documentação;
2. correção de acessibilidade;
3. melhoria visual.

Para cada commit:

• explique o objetivo;
• mostre os arquivos alterados;
• demonstre como validou.

23. Desafio final

Apresente o projeto para outra pessoa sem fornecer instruções verbais de uso.

Observe:

• ela entende a proposta?
• encontra a chamada para ação?
• consegue preencher o formulário?
• entende que é uma simulação?
• consegue recuperar-se de um erro?

Registre três observações e transforme pelo menos uma em melhoria versionada.

24. Erros comuns

Publicar credenciais

Revogue a credencial exposta. Apagar apenas o arquivo atual não remove o dado do histórico.

README genérico

Documente o projeto real, não um modelo vazio.

Link funcionar apenas no computador do autor

Utilize caminhos relativos e teste em outro ambiente.

Commit único com todo o projeto

O histórico perde capacidade de explicar decisões.

Apresentação focada apenas no visual

Demonstre fluxo, acessibilidade, erro, teste e limitações.

Esconder limitações

Limitações bem explicadas demonstram maturidade técnica.

Publicar sem retestar

O ambiente publicado pode se comportar de forma diferente do ambiente local.

25. Lista de verificação de entrega

• Projeto possui README.
• Projeto possui .gitignore.
• Nenhuma credencial foi versionada.
• Commits possuem objetivos claros.
• Diretório de trabalho está no estado esperado.
• Todos os recursos carregam.
• Console está limpo.
• Formulário funciona.
• Sucesso e erro foram testados.
• Navegação por teclado funciona.
• Página funciona em 320 px.
• URL publicada utiliza HTTPS.
• URL foi testada fora da sessão do autor.
• Limitações estão documentadas.
• Apresentação foi ensaiada.
• Projeto foi avaliado pela rubrica.

26. Critérios de aceite

A entrega será aceita quando:

1. estiver acessível por URL;
2. puder ser executada seguindo apenas o README;
3. não possuir credenciais;
4. não apresentar erros no fluxo principal;
5. funcionar por teclado;
6. funcionar entre 320 e 1280 pixels;
7. demonstrar sucesso e erro;
8. possuir histórico compreensível;
9. atingir pelo menos 70 pontos na rubrica;
10. ser apresentada e defendida tecnicamente.

27. Perguntas para revisão

1. Qual é a função do .gitignore?
2. Por que devemos inspecionar git status antes do commit?
3. O que torna um commit compreensível?
4. Quais perguntas um README deve responder?
5. Por que caminhos locais falham após a publicação?
6. O que precisa ser retestado no ambiente publicado?
7. Como demonstrar uma falha de forma segura?
8. O que caracteriza uma boa defesa técnica?
9. Por que limitações devem ser documentadas?
10. O que fazer quando uma credencial é publicada?

Conclusão do módulo

O aluno concluiu a primeira versão publicável da Knowledge AI e demonstrou fundamentos de:

• Web;
• HTML;
• CSS;
• JavaScript;
• acessibilidade;
• responsividade;
• auditoria;
• segurança básica;
• Git;
• documentação;
• publicação.

No Módulo 2, JavaScript será aprofundado para construir aplicações com dados, funções, módulos, assincronismo e consumo de APIs.