# Aula 1.6 - 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`](../materiais/rubrica-projeto-modulo-1.md)
- **Roteiro de apresentação:** [`../materiais/roteiro-apresentacao.md`](../materiais/roteiro-apresentacao.md)
- **README de referência:** [`../exemplos/aula-1.2/README.md`](../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.

```text
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:

```bash
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:

```text
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

| Etapa | Duração |
|---|---:|
| Estado final do projeto | 10 min |
| Git e commits | 25 min |
| README e documentação | 20 min |
| Preparação para publicação | 20 min |
| Publicação e validação | 20 min |
| Apresentação e defesa | 25 min |

## 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

```text
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:

```bash
git init
git status
```

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

### Configuração de identidade

Se necessário:

```bash
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:

```gitignore
.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:

```bash
git status
```

Confirme cada arquivo listado.

## 5. Primeiro commit

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

Não utilize automaticamente:

```bash
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:

```text
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:

```text
ajustes
teste
final
agora vai
alterações diversas
```

## 7. Leitura do histórico

```bash
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:

```bash
git switch -c feature/depoimento
```

Depois:

```bash
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:

```markdown
# 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:

```text
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:

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

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

```text
index.html
assets/
```

## 14. Configuração do caminho

Evite caminhos absolutos locais:

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

Utilize:

```html
<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

```bash
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.