Preparación del entorno de desarrollo

Antes de colaborar con el proyecto zsh-nvm, es necesario configurar un entorno aislado. Verifica que Git y Zsh estén instalados en tu sistema y procede a clonar el repositorio:

git clone https://gitcode.com/gh_mirrors/zs/zsh-nvm

Para evitar conflictos con tu configuración personal de Zsh, crea un archivo de configuración temporal exclusivo para desarrollo:

cd zsh-nvm
DEV_RC="/tmp/.zsh_nvm_dev"
echo "source ${PWD}/zsh-nvm.plugin.zsh" > "$DEV_RC"
zsh -f "$DEV_RC"

Flujo de contribución: de la detección al Pull Request

Deteción y reporte de incidencias

La colaboración normalmente inicia al idetnificar un problema durante el uso del plugin. Consulta primero el tracker de issues del repositorio para verificar si ya existe un reporte similar. Si no lo encuentras, abre un nuevo issue incluyendo:

• Descripción clara del comportamiento inesperado
• Pasos detallados para reproducir el problema
• Información del entorno: versión de Zsh, sistema operativo, versión de nvm
• Salida de error completa si está disponible

Proceso de corrección de errores

Crea una rama dedicada partiendo de la rama principal:

git checkout main
git pull origin main
git checkout -b patch/upgrade-error

El núcleo del plugin reside en el archivo zsh-nvm.plugin.zsh, donde se encuentran las funciones de carga, actualización y envoltura de nvm. Analiza el código fuente y los casos de prueba para localizar el origen del problema.

Tras implementar la corrección, añade pruebas de regresión en el directorio tests/. Ejecuta la suite de pruebas con el framework Urchin para verificar que todo pase correctamente:

urchin -s zsh ./tests

Incorporación de nuevas funcionalidades

Para nuevas características, se recomienda abrir primero un issue de propuesta para discutir la viabilidad con los mantenedores. Los pasos principales son:

1. Diseño: Define los requisitos, casos de uso y la interfaz de configuración (variables de entorno, comandos, etc.)
2. Implementación: Escribe el código siguiendo la estructura existente. Consulta opciones como NVM_LAZY_LOAD como referencia de patrones
3. Documentación: Actualiza el README.md con instrucciones de configuración y ejemplos de uso
4. Cobertura de pruebas: Crea archivos de prueba en tests/options/ o amplía los existentes

Estándares de código y convenciones

Estilo de código

• Usa indentación consistente de 2 espacios
• Prefija las funciones internas con _zsh_nvm_ para evitar colisiones de nombres
• Utiliza MAYÚSCULAS con guiones bajos para variables de entorno (ej: NVM_DIR)
• Incluye comentarios explicativos en lógica compleja

Requisitos de pruebas

• Toda nueva funcionalidad debe incluir pruebas correspondientes
• Las correcciones de bugs deben acompañarse de pruebas de regresión
• Verifica compatibilidad con diferentes versiones de Zsh

Convenciones de comits

• Usa tiempo imperativo: "Fix upgrade error" en lugar de "Fixed upgrade error"
• El mensaje debe describir específicamente el cambio realizado
• Para cambios significativos, incluye contexto adicional en el cuerpo del commit

Uso del framework de pruebas Urchin

Las pruebas se encuentran en el directorio tests/ y cada archivo es un script ejecutable de Zsh. Instala Urchin y ejecuta las pruebas:

# Instalación global
npm i -g urchin

# Ejecutar suite completa
urchin -s zsh ./tests

# Ejecutar prueba individual
urchin -s zsh "./tests/loading/Check zsh-nvm is loaded"

Estructura típica de un archivo de prueba:

#!/usr/bin/env zsh

source "./tests/common.sh"

run_loading_check() {
  local version_output
  version_output=$(nvm --version)
  assert_contains "$version_output" "v"
}

run_loading_check
run_tests

Las funciones utilitarias como aserciones y limpieza de entorno están disponibles en tests/common.sh.

Envío del Pull Request

Una vez completados los cambios y verificados las pruebas, sube tu rama y crea el PR:

git push origin patch/upgrade-error

Al crear el Pull Request, incluye un título descriptivo, una descripción detallada de los cambios, referencia a issues relacionados, y los resultados de las pruebas ejecutadas. Los mantenedores revisarán el código y podrán solicitar ajustes antes de proceder con la integración.

Ejemplos prácticos de contribución

Corrección de bug en obtención de versión

Si el comando nvm upgrade no obtiene correctamente la última versión, revisa la función de obtención de tags y modifícala:

_zsh_nvm_get_latest_tag() {
  builtin cd "$NVM_DIR" || return 1
  git fetch --quiet --tags origin
  local last_tagged
  last_tagged=$(git rev-list --tags --max-count=1)
  git describe --abbrev=0 --tags --match "v[0-9]*" "$last_tagged"
}

Añade el caso de prueba correspondiente en tests/wrapper commands/nvm upgrade.

Nueva funcionalidad: soporte de mirror personalizado

Para añadir una opción de mirror personalizado, define la variable cerca del inicio del archivo principal:

if [[ -z "${NVM_MIRROR_URL}" ]]; then
  export NVM_MIRROR_URL="https://nodejs.org/dist"
fi

Modifica la función de instalación para utilizar el mirror:

case "$2" in
  'rc')
    NVM_NODEJS_ORG_MIRROR="${NVM_MIRROR_URL}/rc/" nvm install node
    nvm alias rc "$(node --version)"
    ;;
esac

Finalmente, documenta la nueva opción en la sección "Options" del README.md.