Issues, commits e troubleshooting

Este capítulo ensina a descrever problema, a nomear commit e a seguir uma lista quando a página da Oficina Costeira “não abre”. O coletivo é fictício, em João Pessoa. O exemplo correspondente é 07-issues-e-troubleshooting, no pacote que acompanha o volume.

Este volume tem 52 capítulos. Ciclo: ler → copiar → mudar uma coisa → prever → recarregar → conferir. Se a conferência falhar, use o checklist antes de mudar mais código.

O que você vai aprender

• Escrever uma issue com título, passos e resultado.
• Manter commits no imperativo.
• Checar save, recarregar, caminho e .txt.
• Desconfiar de cache e da aba errada.
• Separar disco, janela, 127.0.0.1 e publicação.
• Parar e isolar uma causa por vez.

O que é uma issue

Uma issue é um cartão de trabalho: bug, tarefa ou dúvida. No GitHub ela vive na aba Issues do repositório. Sem GitHub, um arquivo ISSUE.md na pasta do estudo cumpre o mesmo papel.

A issue não é o conserto. É o relato. O commit depois aponta para o conserto.

Título curto e específico: Marca some na página Projetos. Não: não funciona.

Corpo mínimo:

1. O que você fez (passos).
2. O que previu.
3. O que viu.
4. Barra de endereço (file:// ou 127.0.0.1).
5. Arquivo e linha, se souber.

Copie este modelo. Troque só o caminho da imagem para um caso real que você provocar no exemplo.

# Marca quebrada no início

Passos: abri index.html, recarreguei.
Previ: o SVG da Oficina Costeira ao lado do nome.
Vi: ícone de imagem quebrada.
URL: file:///B:/.../07-issues-e-troubleshooting/index.html
Arquivo: index.html, atributo src de img

Markdown curto na issue

Negrito, lista e trecho de código ajudam quem lê.

O `src` atual é:

    assets/imagens/Marca.svg

O arquivo no disco é `marca.svg`.

Não cole senha. Não cole dado pessoal. O conteúdo da Oficina Costeira já é fictício; mantenha assim.

Se houver remoto, uma issue no GitHub pode citar commit depois. Localmente, o hábito já vale.

Erro comum: issue que só diz “ajuda”. Sem passos, ninguém reproduz. Inclusive você amanhã.

Commit descreve o conserto

Depois de corrigir uma causa:

git add index.html
git commit -m "Corrige o caminho da marca no início"

Imperativo. Sem ponto final. Uma ideia por commit. Não junte “arruma CSS, HTML e o nome da pasta” no mesmo fotografia se forem problemas distintos.

Se a issue for #4 num remoto, a mensagem pode terminar com Corrige o caminho da marca. O número da issue fica no corpo, não no lugar do verbo.

Não reescreva histórico enviado. Sem push --force.

Checklist geral

Pare. Uma pergunta por vez.

1. Salvou com Ctrl+S?
2. Recarregou a aba certa?
3. A barra mostra o arquivo que você editou?
4. A extensão é .html, não .html.txt?
5. O nome no src ou href bate com o disco, em minúsculas?
6. Está em file:// quando o caminho começa com /?
7. Servidor em 127.0.0.1 ainda está no ar?
8. Recarregou de novo depois de uns segundos (cache)?
9. Fechou e abriu o navegador se uma extensão estranha interferir?
10. Já é hora de um intervalo?

Não pule para “reinstalar o editor”. A causa mais comum neste volume é caminho, .txt ou aba velha.

Checklist HTML e CSS

HTML:

• Tag escrita certo: </h1>, não <h1>.
• Atributo entre aspas.
• lang="pt-BR" no html.
• link do CSS no head, caminho relativo correto.

CSS (quando existir main.css):

• Seletor existe no HTML.
• Ponto no nome da classe: .menu.
• Ponto e vírgula no fim da declaração.
• Chaves { } aos pares.
• color com a grafia da linguagem CSS.

Valide em Validador HTML colando o código de estudo, sem dado real.

Provoco didático: no exemplo, renomeie mentalmente main.css no href para main.css.txt. Preveja página sem estilo. Não precisa gravar o erro. Só reconhecer o padrão.

Disco, janela, localhost, publicação

Quando a “página no ar” não muda:

• Disco: o editor salvou?
• Janela: a aba é a da Oficina Costeira deste exemplo, não do capítulo 01?
• 127.0.0.1: o Python ainda está ligado? A porta é 8769? O bind é 127.0.0.1?
• Publicação: este volume não exige. Se um dia houver Pages, espere o envio e o cache do CDN. Não é o caso do exercício.

Erro comum: editar exemplos/07-issues-e-troubleshooting/index.html e recarregar exemplos/06-git-e-github/index.html. Compare a barra com a pasta do editor.

Uma causa por vez

O ciclo de estudo vira ciclo de defeito: ler o sintoma → copiar o arquivo para um teste mínimo → mudar uma coisa → prever → recarregar → conferir.

Se você mudar caminho, classe e texto juntos, não saberá o que curou. Volte o extra. Deixe uma alteração.

Issue fecha quando o resultado bate com a previsão e o commit está no histórico local. GitHub opcional.

Checklist Git, se o remoto existir: commit feito? push feito? e-mail da conta verificado? pasta certa (Repository: show in folder)? Sem isso, a “cópia na nuvem” mente e o disco está certo — ou o contrário.

Não transforme a issue em pedido de pontuação. Ela é o seu rastro. Cole trecho de código, não a pasta inteira.

Provoco guiado no exemplo 07:

1. Salve index.html.
2. Quebre o href do CSS.
3. Recarregue. Preveja página sem estilo.
4. Escreva a issue com a URL da barra.
5. Restaure o caminho. Commit: Corrige o href do CSS no início.

Se o estilo não voltar, volte ao item 1 do checklist geral. Cache. Aba. Extensão .txt.

Ferramentas de desenvolvedor (F12): aba Rede mostra arquivo 404. Aba Console mostra erro de JS, que nesta série quase não existe. Aba Elementos mostra a árvore. Use Rede para caminho; use Elementos para tag.

Se duas pessoas editam o mesmo remoto, puxe antes de enviar. Conflito se resolve no disco, commit novo, push simples. Sem força.

Ainda travado? Feche o navegador por completo, não só a aba. Abra de novo a URL que está na barra do editor. Compare letra por letra com o Explorador. Maiúscula no meio do src é o vilão clássico.

Imagem que não carrega: o HTML pode estar certo e o arquivo em outra pasta. assets/imagens não é imagens. marca.svg não é marca.png. Anote os três: pasta, nome, extensão.

Pare. Uma causa. Só então o próximo item do checklist.

Atividades

1. Quais quatro blocos uma issue útil precisa ter?
2. Qual mensagem de commit descreve melhor o conserto de um src errado?
3. Cite três itens do checklist que vêm antes de “validar no sítio do W3C”.
4. No exemplo, provoque um caminho errado, registre a issue em um bloco de notas e depois corrija. O que mudou na barra e na janela?

Respostas comentadas

1. Passos, previsão, resultado visto e contexto (URL + arquivo). Título específico completa o cartão.
2. Algo como Corrige o src da marca no início. Imperativo, arquivo e sintoma. Não ajustes finais.
3. Salvar, recarregar a aba certa, conferir extensão .html e conferir o caminho no disco. Validar ajuda depois, não no lugar disso.
4. Com o caminho errado, a imagem quebra. Com o caminho certo e save, a marca volta. A URL da página em geral não muda; muda o recurso pedido. Se você estava em file://, continue nessa barra até decidir testar 127.0.0.1.

Referências

• Depuração HTML
• O que são ferramentas de desenvolvedor
• Validador de marcação W3C
• Git

O arquivo completo

Referência do exemplo 07-issues-e-troubleshooting, reproduzida aqui para que você possa conferir sem sair da página.

assets/javascript/simulacao.js

const form=document.querySelector("#simulacao");if(form){form.querySelector("button[type=submit]").disabled=false;form.addEventListener("submit",event=>{event.preventDefault();document.querySelector("#retorno").textContent="Simulação concluída. Nada foi enviado ou guardado.";});}