SpeakingColors/claude-skills

GitHub para iniciantes

Skill comunitária não oficial. Os fatos são verificados em relação à documentação oficial do GitHub, onde indicado (V). Não é aconselhamento jurídico.

Estilo (seguir rigorosamente)

• Assumir que o usuário não sabe nada e não quer aprender Git. Ele quer o resultado.
• Dar um passo de cada vez. Nomear o botão exato ou o texto do link que ele verá. Aguardar ele dizer que terminou antes de dar o próximo passo.
• Começar com um resumo de uma linha. Detalhes apenas quando solicitados.
• Se ele enviar uma captura de tela, lê-la e dizer onde ele está antes da próxima instrução.
• Se você (o assistente) pode executar a etapa sozinho com acesso ao repositório, oferecer-se para fazê-lo. Solicitar acesso através da ferramenta adequada ou fluxo de login. Nunca pedir para ele colar uma senha ou token de acesso no chat.

1. Criar um repositório

1. Clicar no + no canto superior direito do github.com e depois em Novo repositório.
2. Nome: curto, minúsculas, hífens (por exemplo, meu-plugin).
3. Escolher Público (qualquer um pode ver) ou Privado.
4. Marcar Adicionar um README. Escolher uma licença no menu suspenso (veja a seção 5).
5. Clicar em Criar repositório.

Um repositório vazio mostra uma página "Configuração rápida" com caixas de linha de comando. Um iniciante pode ignorar tudo ali e usar o link "fazer upload de um arquivo existente".

2. Colocar arquivos no repositório (web, sem Git)

Na página do repositório: Adicionar arquivo, depois Fazer upload de arquivos. Arrastar arquivos ou clicar em "escolher seus arquivos".

Limites (V: docs do GitHub, Adicionar um arquivo a um repositório):

• 25 MiB por arquivo ao fazer upload no navegador.
• Até 100 arquivos por upload.
• Arquivos maiores, até 100 MiB cada, precisam da linha de comando; arquivos acima de 100 MiB precisam do Git Large File Storage.
• Um branch protegido não pode ser editado através do upload web.
• A proteção contra push pode bloquear um arquivo contendo um segredo suportado, como um token.

Pastas: a documentação diz que você pode arrastar um arquivo ou pasta. Se o navegador do usuário não aceitar uma pasta, usar uma destas alternativas:

• Criar a pasta no editor web: Adicionar arquivo, Criar novo arquivo, digitar nomedapasta/nomedoarquivo.md na caixa de nome (digitar a barra cria a pasta), adicionar conteúdo e depois commit. Verificar o comportamento na interface atual.
• Descompactar a pasta e fazer upload dos arquivos em lotes que mantenham seus caminhos de pasta, ou usar o GitHub Desktop.
• Deixar o assistente enviar os arquivos se ele tiver acesso ao repositório.

Arquivos zip são armazenados como um único arquivo; o GitHub não os descompacta. Fazer upload do conteúdo descompactado.

Finalizar com uma mensagem de commit (curta, o que mudou) e o botão Confirmar alterações.

Verificar o resultado: abrir a página do repositório e comparar a lista de arquivos com o que foi pretendido. Erro comum: arquivos caem na raiz em vez de dentro de sua pasta.

3. Releases com downloads (o que os usuários devem baixar)

Um release é uma página de download rotulada baseada em uma tag Git (V: docs do GitHub, Sobre releases).

1. Na página do repositório, clicar em Releases (lado direito) e depois em Rascunhar um novo release.
2. Escolher uma tag como v1.0.0 (digitar uma nova e depois Criar nova tag).
3. Título e notas: o que é, como instalar em três passos, o que mudou.
4. Arrastar os arquivos para a caixa de assets. Releases amigáveis para iniciantes incluem um instalador ou arquivo compilado por sistema operacional, um manual curto e instruções de instalação, não apenas um arquivo simples ou o código-fonte.
5. Clicar em Publicar release.

Limites (V): cada arquivo abaixo de 2 GiB, até 1000 assets por release, sem limite de tamanho total ou largura de banda.

Modelo de notas de release:

• O que é (uma linha)
• Download: escolha seu sistema (Windows, macOS, Linux)
• Instalar em três passos
• Checksums (SHA-256) para cada arquivo
• Problemas conhecidos

4. Licença e fundamentos do README

• Um repositório sem licença não é código aberto; outros não têm o direito de reutilizá-lo. Escolher uma deliberadamente.
• MIT: muito permissiva, curta. AGPL-3.0 ou GPL: compartilhamento igual (copyleft). Projetos construídos com JUCE em sua opção de código aberto são cobertos pela AGPLv3 (V: fórum JUCE, equipe), portanto verificar a licença atual do JUCE antes de escolher.
• Nunca publicar arquivos de fornecedores (manuais, presets de fábrica, logotipos, binários) dos quais você não possui os direitos. Vincular a eles.
• O README deve responder: o que é, como instalar, como usar, licença, como relatar problemas.

5. Manter informações privadas fora (mais importante)

Antes do primeiro push público, pesquisar em cada arquivo e na identidade do commit por: nome real, e-mail pessoal, telefone, endereço, empregador, tokens, senhas, caminhos locais com o nome de usuário.

Identidade do commit:

• Usar o endereço noreply do GitHub, mostrado em Configurações, E-mails, com a opção "Manter meus endereços de e-mail privados" marcada. Formato: <id numérico>+<nome de usuário>@users.noreply.github.com.
• Definir antes de commitar: git config user.name "<nome de usuário>" e git config user.email "<id>+<nome de usuário>@users.noreply.github.com". Verificar com git log --format='%an <%ae>' antes de fazer push.
• Quando um assistente commita pelo usuário, deve usar essa identidade e nunca o e-mail real do usuário.

Se dados privados já foram tornados públicos (V: docs do GitHub, Removendo dados confidenciais de um repositório):

1. Se for uma credencial, revogá-la ou rotacioná-la primeiro. Isso pode ser suficiente por si só.
2. Reescrever o histórico localmente com git-filter-repo (versão 2.47 ou posterior para --sensitive-data-removal). Remover um arquivo com --invert-paths --path ou substituir texto com --replace-text.
3. Forçar push para sobrescrever o repositório no GitHub.
4. Entrar em contato com o Suporte do GitHub para remover visualizações em cache e referências de pull requests; fornecer o nome do repositório, número de PRs afetados e os primeiros commits alterados da saída da ferramenta.
5. Forks mantêm os dados; pedir aos proprietários do fork para removê-los. Colaboradores devem fazer rebase, não merge.
6. Aviso da documentação: os clones de outras pessoas mantêm os dados, e uma reescrita pode revelar o que foi removido. Assumir que os dados foram vistos.

Alterar (amend) um commit recente é suficiente apenas para a ponta do branch; o commit antigo ainda pode ser acessado por seu link direto até que o GitHub faça a limpeza, então o passo 4 ainda se aplica.

5b. Escolhendo o que vai para o público

• Notas de pesquisa, dados de dispositivo capturados, notas pessoais e transcrições de chat não pertencem a um repositório público, a menos que o usuário diga o contrário.
• Perguntar antes de publicar qualquer coisa que não foi escrita para o público.

6. Tarefas do dia a dia (uma de cada vez)

• Editar um arquivo na web: abri-lo, ícone de lápis, alterar, Confirmar alterações.
• Excluir um arquivo: abri-lo, três pontos, Excluir arquivo, confirmar.
• Renomear ou mover: editar a caixa de nome do arquivo, digitando o novo caminho; confirmar.
• Fixar um repositório no perfil: página do perfil, Personalizar seus pins.
• Ativar uma página web do projeto (GitHub Pages): Configurações, Pages, escolher o branch e a pasta. Verificar a interface atual.
• Relatar ou acompanhar problemas: aba Issues. Oferecer um modelo de issue para relatos de bugs.

7. Quando algo falha

• Upload recusado: verificar tamanho do arquivo (limite web de 25 MiB), número de arquivos (100) e branch protegido.
• Pasta ausente: arquivos foram enviados de forma plana; recriar o caminho com Criar novo arquivo ou reenviar.
• Push rejeitado com aviso de segredo: remover o segredo, rotacioná-lo e tentar novamente.
• Nunca sugerir desabilitar prompts de segurança.

Fontes

• Documentação do GitHub, Adicionar um arquivo a um repositório: https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository
• Documentação do GitHub, Sobre releases: https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
• Documentação do GitHub, Removendo dados confidenciais de um repositório: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository