OpenGHz/open-source-project-polish

Polimento de Projeto Open Source

Objetivo

Transformar uma pasta de projeto existente em um repositório open source de alta qualidade, melhorando a documentação pública, arquivos da comunidade, metadados do repositório e configuração Git/GitHub, preservando o código-fonte original.

Limites Rígidos

• Não modificar o código/produto original, lógica gerada, testes, notebooks, assets ou comportamento em tempo de execução, a menos que o usuário peça explicitamente.
• As alterações permitidas são limitadas a metadados e documentação do projeto, como README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CHANGELOG, SUPPORT, CITATION, templates de issue/PR, notas de release, badges, .gitignore, .gitattributes, .editorconfig e scaffolding de workflow/documentação do GitHub.
• Nunca incluir caminhos de máquina local específicos do usuário no README ou em documentos públicos, como /home/<usuário>/..., /Users/<usuário>/..., caminhos com letra de unidade, nomes de workspace pessoais, pastas de download ou caminhos absolutos de projeto específicos da máquina. Usar caminhos relativos, $HOME, <repo> ou placeholders.
• Padrão para licenciamento MIT quando não existir licença e não houver preferência do usuário.
• Padrão para publicação pública automatizada no GitHub para pastas sem remote Git. Determinar o dono/nome do repositório de destino se não for óbvio, depois criar um remote público e enviar apenas alterações de documentação após verificações de segredos.
• Se um comando de rede/GitHub falhar, tentar novamente uma vez com o proxy local configurado antes de declarar a etapa remota como bloqueada.
• Preservar documentos e arquivos da comunidade existentes sempre que possível; melhorá-los incrementalmente em vez de substituir conteúdo útil.

Entradas a Esclarecer Quando Ausentes

Perguntar apenas por informações que afetem materialmente ações irreversíveis ou públicas:

1. Escopo do destino: caminho do projeto no workspace, ou pasta atual se já estiver claro.
2. Identidade pública: dono/nome do repositório no GitHub antes de criar qualquer remote se não puder ser inferido da pasta e da conta autenticada no GitHub.
3. Substituição de licença: usar uma licença existente se presente; caso contrário, aplicar MIT por padrão, a menos que o usuário solicite outra licença.
4. Posicionamento do projeto: proposta de valor em uma frase, público-alvo e maturidade se não for inferível do código/documentação.
5. Edições no código-fonte: assumir como proibido; perguntar antes de tocar em qualquer coisa além de metadados/documentação.

Procedimento

1. Auditar o Estado do Projeto

• Inspecionar a estrutura de pastas, README/documentação existentes, manifestos de pacotes, arquivos de build, exemplos, arquivos de licença e estado do Git.
• Verificar se .git existe e se algum remote está configurado.
• Identificar arquivos com risco de segredos antes de qualquer criação de remote ou push: .env, credenciais, tokens, binários grandes, datasets, anotações privadas, logs locais e caminhos específicos da máquina.
• Resumir pontos fortes existentes, itens essenciais de open source ausentes e qualquer incerteza que precise de entrada do usuário.

2. Planejar Adições Não Relacionadas a Código

Criar um plano conciso cobrindo apenas trabalho permitido de documentação e metadados:

• Melhorias no README usando a skill create-readme como base para estrutura, tom e Markdown no estilo GitHub.
• README bilíngue por padrão: após finalizar o README principal (em inglês), produzir uma versão em chinês salva como README.zh-CN.md e fazer links cruzados entre os dois. Escrever a tradução diretamente; reservar a skill baoyu-translate para documentos longos ou com terminologia densa onde a consistência global de termos é importante.
• Arquivos de saúde da comunidade: licença MIT por padrão, guia de contribuição, código de conduta, política de segurança, guia de suporte, changelog, citação, governança, templates de issue, template de PR.
• Higiene do repositório: .gitignore, .gitattributes, .editorconfig, índice de documentação, índice de exemplos, badges, descrição do projeto, tópicos, metadados de financiamento/patrocinador se relevante.
• Configuração Git/GitHub: inicializar Git se ausente, criar remote público se ausente, definir branch padrão e enviar apenas alterações de documentação após verificações de segurança.

3. Melhorar o README

Usar a skill create-readme para criação ou atualização do README. Garantir que o README seja conciso, atraente e útil:

• Nome claro do projeto, slogan e proposta de valor curta.
• Badges apenas quando verdadeiros e sustentáveis.
• Início rápido com comandos verificados quando possível.
• Os comandos devem ser copiáveis da raiz do repositório e não devem conter caminhos absolutos locais do usuário atual; preferir exemplos como ./script.sh, $HOME/..., /caminho/para/... ou <repo>/....
• Instalação, uso, configuração, exemplos, estrutura do projeto, solução de problemas e links para arquivos dedicados.
• Não duplicar conteúdo completo de LICENSE, CONTRIBUTING, CHANGELOG ou SECURITY dentro do README; linkar para esses arquivos.
• Preservar conhecimento e exemplos específicos do projeto existentes.

Após finalizar o README.md em inglês, produzir uma tradução para chinês por padrão:

• O README.md em inglês deve incluir uma linha de troca de idioma perto do topo por padrão, ex. English | [简体中文](README.zh-CN.md). Adicioná-la mesmo quando o arquivo chinês ainda está sendo gerado na mesma execução — o link aponta para o caminho que existirá quando o workflow for concluído.
• Produzir o README.zh-CN.md em chinês a partir do README.md. Escrever a tradução diretamente é preferível para um README típico (principalmente prosa curta mais código/comandos que devem permanecer literais); invocar a skill baoyu-translate apenas quando o README for longo ou com terminologia densa e se beneficiar do fluxo analisar/traduzir/revisar e de um glossário compartilhado.
• O README.zh-CN.md em chinês carrega a linha de troca de idioma no topo, ex. [English](README.md) | 简体中文.
• Manter todos os blocos de código, comandos, caminhos, links, badges e placeholders inalterados; traduzir apenas prosa.
• Pular a versão em chinês apenas se o usuário optar explicitamente. Se o projeto já for escrito principalmente em chinês, tratar README.md como a versão chinesa, traduzir para README.en.md e colocar a linha de troca de idioma correspondente no topo de cada arquivo.

4. Adicionar Arquivos da Comunidade

Adicionar ou atualizar arquivos apenas quando eles ajudarem o projeto a parecer completo e confiável:

• LICENSE: usar licença existente se presente; caso contrário, adicionar MIT por padrão com o ano atual detectado e nome do dono/projeto onde apropriado.
• CONTRIBUTING.md: configuração de desenvolvimento, convenções de branch/commit se inferíveis, expectativas de teste, processo de issue/PR.
• CODE_OF_CONDUCT.md: usar um estilo padrão de pacto de contribuidor conciso, a menos que o usuário tenha outra política.
• SECURITY.md: versões suportadas, placeholder para canal de divulgação responsável, expectativas de reporte de vulnerabilidades.
• CHANGELOG.md: inicializar com Unreleased e linha de base pública atual; não inventar histórico de releases.
• SUPPORT.md: onde fazer perguntas, reportar bugs e solicitar funcionalidades.
• .github/ISSUE_TEMPLATE/* e .github/PULL_REQUEST_TEMPLATE.md: formulários/checklists práticos adaptados ao projeto.
• CITATION.cff apenas para projetos de pesquisa/acadêmicos/científicos ou quando metadados de autoria estiverem disponíveis.

5. Higiene do Repositório

• Criar ou refinar .gitignore com base em linguagens/ferramentas detectadas, sem excluir arquivos que provavelmente são artefatos de código-fonte.
• Adicionar .gitattributes para normalização de texto e padrões comuns de binários quando útil.
• Adicionar .editorconfig com padrões conservadores de espaço em branco correspondentes ao estilo do repositório.
• Não adicionar workflows de CI a menos que comandos de build/teste sejam conhecidos ou verificados; se adicionados, mantê-los mínimos e não invasivos.

6. Manipulação de Git e Remote

Para pastas sem Git:

1. Inicializar um repositório para a pasta de destino após verificar o caminho da pasta.
2. Stagiar apenas arquivos de metadados/documentação criados ou alterados por este workflow.
3. Fazer commit com uma mensagem focada em documentação quando a publicação estiver prosseguindo.

Para repositórios Git sem um remote:

1. Inferir o dono do GitHub a partir da autenticação gh e o nome do repositório a partir da pasta quando possível; perguntar apenas se ambíguo.
2. Verificar a autenticação gh antes de criar um remote.
3. Criar um repositório público no GitHub por padrão.
4. Adicionar origin, definir a branch padrão e fazer push após revisar as alterações staged e confirmar que nenhum segredo está incluído.

Fluxo recomendado da CLI do GitHub, adaptado ao projeto:

git status --short
git remote -v
gh auth status
gh repo create OWNER/REPO --public --source=. --remote=origin --push

Se comandos de rede falharem, tentar novamente uma vez com:

export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890

7. Verificações de Qualidade

Antes de finalizar:

• Reabrir snippets de Markdown alterados para verificar cabeçalhos, links, fences de código e indentação de comandos copiáveis.
• Pesquisar no README e documentos públicos por caminhos de máquina local antes de finalizar, incluindo /home/, /Users/, caminhos com letra de unidade, nomes de workspace pessoais e caminhos absolutos copiados do ambiente atual.
• Confirmar que nenhum arquivo de código-fonte foi modificado, a menos que aprovado explicitamente.
• Confirmar que todos os links para arquivos locais apontam para arquivos que existem.
• Se um README em chinês foi produzido, confirmar que README.zh-CN.md existe, que os links de troca de idioma resolvem em ambos os arquivos e que código/comandos/caminhos permanecem idênticos à versão em inglês.
• Executar formatação leve ou linting de Markdown se disponível; não instalar dependências pesadas apenas para este workflow, a menos que o usuário concorde.
• Mostrar git diff --stat e resumir arquivos alterados.
• Se um remote foi criado, relatar a URL, visibilidade, branch padrão e se algo foi enviado.

Pontos de Decisão

• README existente é forte: preservar estrutura e corrigir seções ausentes em vez de reescrever.
• Nenhum comando de instalação/teste verificado: incluir placeholders claramente marcados ou notas "ainda não documentado" em vez de inventar comandos.
• Licença desconhecida: adicionar MIT por padrão, a menos que o usuário solicite uma licença diferente.
• Possíveis segredos ou dados privados: interromper criação/push remoto e reportar os caminhos arriscados.
• Sem CLI gh ou não autenticado: fornecer comandos exatos para o usuário executar, mas ainda concluir o polimento da documentação local e preparar um commit apenas de documentação, se seguro.
• Monorepo: criar ou atualizar arquivos raiz da comunidade e arquivos README por pacote apenas quando os limites do pacote estiverem claros.

Resumo de Conclusão

Terminar com:

• Arquivos adicionados/atualizados.
• O que não foi intencionalmente tocado, especialmente código-fonte.
• Validação realizada.
• Status do repositório remoto, se aplicável.
• Próximos passos sugeridos, como habilitar CI, adicionar exemplos, fazer um primeiro release ou criar tópicos do projeto.