OpenGHz/open-source-project-polish

Open Source Project Polish

Objetivo

Transformar una carpeta de proyecto existente en un repositorio de código abierto de alta calidad mejorando la documentación pública, los archivos comunitarios, los metadatos del repositorio y la configuración de Git/GitHub, preservando el código fuente original.

Límites estrictos

• No modificar el código fuente original, lógica generada, pruebas, notebooks, activos o comportamiento en tiempo de ejecución a menos que el usuario lo solicite explícitamente.
• Los cambios permitidos se limitan a metadatos y documentación orientados al proyecto, como README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CHANGELOG, SUPPORT, CITATION, plantillas de issues/PR, notas de versión, insignias, .gitignore, .gitattributes, .editorconfig y andamios de flujos de trabajo/docs de GitHub.
• Nunca incluir rutas locales específicas del usuario en README o documentos públicos, como /home/<usuario>/..., /Users/<usuario>/..., rutas de letra de unidad, nombres de espacios de trabajo personales, carpetas de descargas o rutas absolutas del proyecto específicas de la máquina. Usar rutas relativas, $HOME, <repo> o marcadores de posición.
• Por defecto, licencia MIT cuando no exista licencia y no haya preferencia del usuario que la anule.
• Por defecto, publicación pública automatizada en GitHub para carpetas sin un remoto Git. Determinar el propietario/nombre objetivo si no es obvio, luego crear un remoto público y enviar cambios solo de documentación después de que las comprobaciones de secretos pasen.
• Si falla un comando de red/GitHub, reintentar una vez con el proxy local configurado antes de declarar bloqueado el paso remoto.
• Preservar documentos y archivos comunitarios existentes cuando sea posible; mejorarlos de forma incremental en lugar de reemplazar contenido útil.

Entradas a aclarar cuando faltan

Preguntar solo por información que afecte materialmente acciones irreversibles o públicas:

1. Alcance objetivo: ruta del proyecto en el espacio de trabajo, o carpeta actual si ya está clara.
2. Identidad pública: propietario/nombre del repositorio de GitHub antes de crear cualquier remoto si no se puede inferir de la carpeta y la cuenta autenticada de GitHub.
3. Anulación de licencia: usar una licencia existente si está presente; de lo contrario, aplicar MIT por defecto a menos que el usuario solicite otra licencia.
4. Posicionamiento del proyecto: propuesta de valor de una frase, usuarios objetivo y madurez si no se puede inferir del código/documentación.
5. Ediciones de código fuente: asumir prohibidas; preguntar antes de tocar cualquier cosa más allá de metadatos/documentación.

Procedimiento

1. Auditar el estado del proyecto

• Inspeccionar la estructura de la carpeta, README/documentos existentes, manifiestos de paquetes, archivos de compilación, ejemplos, archivos de licencia y estado de Git.
• Verificar si existe .git y si hay algún remoto configurado.
• Identificar archivos con riesgo de secretos antes de cualquier creación de remoto o envío: .env, credenciales, tokens, binarios grandes, conjuntos de datos, notas privadas, registros locales y rutas específicas de la máquina.
• Resumir fortalezas existentes, carencias esenciales de código abierto y cualquier incertidumbre que necesite entrada del usuario.

2. Planificar adiciones sin código

Crear un plan conciso que cubra solo el trabajo de documentación y metadatos permitido:

• Mejoras de README usando la habilidad create-readme como base para estructura, tono y Markdown con estilo GitHub.
• README bilingüe por defecto: después de finalizar el README principal (en inglés), producir una versión en chino guardada como README.zh-CN.md y enlazar ambos. Redactar el espejo directamente; reservar la habilidad baoyu-translate para documentos largos o con mucha terminología donde la consistencia global de términos sea importante.
• Archivos de salud comunitaria: licencia MIT por defecto, guía de contribución, código de conducta, política de seguridad, guía de soporte, changelog, cita, gobernanza, plantillas de issues, plantilla de PR.
• Higiene del repositorio: .gitignore, .gitattributes, .editorconfig, índice de documentación, índice de ejemplos, insignias, descripción del proyecto, temas, metadatos de financiamiento/patrocinio si corresponde.
• Configuración de Git/GitHub: inicializar Git si está ausente, crear remoto público si está ausente, establecer rama por defecto y enviar cambios solo de documentación después de las comprobaciones de seguridad.

3. Mejorar README

Usar la habilidad create-readme para la creación o actualización del README. Asegurar que el README sea conciso, atractivo y útil:

• Nombre claro del proyecto, eslogan y propuesta de valor corta.
• Insignias solo cuando sean veraces y mantenibles.
• Inicio rápido con comandos verificados cuando sea posible.
• Los comandos deben ser copiables desde la raíz del repositorio y no deben contener rutas absolutas locales del usuario actual; preferir ejemplos como ./script.sh, $HOME/..., /ruta/a/... o <repo>/....
• Instalación, uso, configuración, ejemplos, estructura del proyecto, solución de problemas y enlaces a archivos dedicados.
• No duplicar el contenido completo de LICENSE, CONTRIBUTING, CHANGELOG o SECURITY dentro del README; enlazar a esos archivos.
• Preservar el conocimiento y ejemplos específicos del proyecto existentes.

Después de finalizar el README en inglés README.md, producir una traducción al chino por defecto:

• El README.md en inglés debe incluir una línea de cambio de idioma cerca de la parte superior por defecto, por ejemplo English | [简体中文](README.zh-CN.md). Añadirla incluso cuando el archivo chino aún se esté generando en la misma ejecución; el enlace apunta a la ruta que existirá cuando el flujo de trabajo se complete.
• Producir el README.zh-CN.md en chino a partir de README.md. Se prefiere redactar el espejo directamente para un README típico (mayormente prosa corta más código/comandos que deben permanecer textuales); invocar la habilidad baoyu-translate solo cuando el README es largo o con mucha terminología y se beneficie de su flujo de analizar/traducir/revisar y un glosario compartido.
• El README.zh-CN.md en chino lleva la línea de cambio de espejo en la parte superior, por ejemplo [English](README.md) | 简体中文.
• Mantener todos los bloques de código, comandos, rutas, enlaces, insignias y marcadores de posición sin cambios; traducir solo la prosa.
• Omitir la versión en chino solo si el usuario lo rechaza explícitamente. Si el proyecto ya está redactado principalmente en chino, tratar README.md como la versión china, traducir a README.en.md y poner la línea de cambio correspondiente en la parte superior de cada archivo.

4. Añadir archivos comunitarios

Añadir o actualizar archivos solo cuando ayuden a que el proyecto parezca completo y confiable:

• LICENSE: usar licencia existente si está presente; de lo contrario, añadir MIT por defecto con el año actual detectado y propietario/nombre del proyecto donde corresponda.
• CONTRIBUTING.md: configuración de desarrollo, convenciones de rama/commit si se pueden inferir, expectativas de pruebas, proceso de issues/PR.
• CODE_OF_CONDUCT.md: usar un estilo estándar de pacto de contribuyente conciso a menos que el usuario tenga otra política.
• SECURITY.md: versiones compatibles, marcador de posición del canal de divulgación responsable, expectativas de reporte de vulnerabilidades.
• CHANGELOG.md: inicializar con Unreleased y línea base pública actual; no inventar historial de versiones.
• SUPPORT.md: dónde hacer preguntas, reportar errores y solicitar características.
• .github/ISSUE_TEMPLATE/* y .github/PULL_REQUEST_TEMPLATE.md: formularios/checklists prácticos adaptados al proyecto.
• CITATION.cff solo para proyectos de investigación/académicos/científicos o cuando haya metadatos de autoría disponibles.

5. Higiene del repositorio

• Crear o refinar .gitignore basado en lenguajes/herramientas detectados sin excluir archivos que probablemente sean artefactos fuente.
• Añadir .gitattributes para normalización de texto y patrones binarios comunes cuando sea útil.
• Añadir .editorconfig con valores predeterminados conservadores de espacios en blanco que coincidan con el estilo del repositorio.
• No añadir flujos de trabajo de CI a menos que se conozcan o verifiquen comandos de compilación/prueba; si se añaden, mantenerlos mínimos y no invasivos.

6. Manejo de Git y remoto

Para carpetas sin Git:

1. Inicializar un repositorio para la carpeta objetivo después de verificar la ruta de la carpeta.
2. Preparar solo archivos de metadatos/documentos creados o modificados por este flujo de trabajo.
3. Confirmar con un mensaje centrado en documentación cuando se proceda a la publicación.

Para repositorios Git sin un remoto:

1. Inferir el propietario de GitHub desde la autenticación gh y el nombre del repositorio desde la carpeta cuando sea posible; preguntar solo si es ambiguo.
2. Verificar la autenticación gh antes de crear un remoto.
3. Crear un repositorio público de GitHub por defecto.
4. Añadir origin, establecer la rama por defecto y enviar después de revisar los cambios preparados y confirmar que no hay secretos incluidos.

Flujo recomendado de GitHub CLI, adaptado al proyecto:

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

Si fallan los comandos de red, reintentar una vez con:

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

7. Controles de calidad

Antes de finalizar:

• Reabrir fragmentos de Markdown modificados para verificar encabezados, enlaces, bloques de código y sangrías de comandos copiables.
• Buscar en README y documentos públicos rutas locales de la máquina antes de finalizar, incluyendo /home/, /Users/, rutas de letra de unidad, nombres de espacios de trabajo personales y rutas absolutas copiadas del entorno actual.
• Confirmar que no se modificaron archivos de código fuente a menos que se haya aprobado explícitamente.
• Confirmar que todos los enlaces a archivos locales apuntan a archivos que existen.
• Si se produjo un README en chino, confirmar que existe README.zh-CN.md, los enlaces de cambio de idioma se resuelven en ambos archivos y el código/comandos/rutas permanecen idénticos a la versión en inglés.
• Ejecutar formateo ligero o marcado de Markdown si está disponible; no instalar dependencias pesadas solo para este flujo de trabajo a menos que el usuario esté de acuerdo.
• Mostrar git diff --stat y resumir los archivos modificados.
• Si se creó un remoto, reportar la URL, visibilidad, rama por defecto y si se envió algo.

Puntos de decisión

• README existente sólido: preservar la estructura y parchear secciones faltantes en lugar de reescribir.
• No hay comandos de instalación/prueba verificados: incluir marcadores de posición claramente marcados o notas de "aún no documentado" en lugar de inventar comandos.
• Licencia desconocida: añadir MIT por defecto a menos que el usuario solicite una licencia diferente.
• Posibles secretos o datos privados: detener la creación/envío remoto y reportar las rutas riesgosas.
• No hay CLI gh o no está autenticado: proporcionar comandos exactos para que el usuario los ejecute, pero aún así completar el pulido de documentos locales y preparar una confirmación solo de documentación si es seguro.
• Monorepo: crear o actualizar archivos comunitarios raíz y archivos README por paquete solo cuando los límites del paquete estén claros.

Resumen de finalización

Terminar con:

• Archivos añadidos/actualizados.
• Lo que no se tocó intencionalmente, especialmente el código fuente.
• Validación realizada.
• Estado del repositorio remoto, si corresponde.
• Próximos pasos sugeridos como habilitar CI, añadir ejemplos, hacer un primer lanzamiento o crear temas del proyecto.