Guía de desarrollo del repositorio de código#
Especificación de código#
Escribir buen código no solo depende de lo que escribes, sino de cómo lo escribes. Durante las pruebas de integración continua, múltiples herramientas verifican tu código en busca de errores de estilo. Un buen estilo de programación es uno de los requisitos para enviar código a Xinference.
Además, no realices cambios bruscos en el código, ya que podrían causar problemas en una gran cantidad de código de usuario. Por lo tanto, debemos mantener la compatibilidad hacia atrás tanto como sea posible para evitar fallos a gran escala.
Corregir automáticamente errores de formato#
Además, la integración continua ejecutará herramientas de verificación de formato de código como black, flake8, isort, utilizando pre-commit hooks. Cualquier advertencia generada por estas verificaciones hará que la integración continua falle. Por lo tanto, se recomienda ejecutar estas verificaciones localmente antes de enviar el código. Esto se puede hacer instalando pre-commit en el directorio raíz del repositorio de Xinference:
pip install pre-commit
Luego ejecute el comando:
pre-commit install
Una vez instalado, garantiza que cada vez que se realice una confirmación de cambios se ejecuten automáticamente todas las verificaciones de estilo, sin necesidad de ejecutarlas manualmente una por una. Además, usar pre-commit también le facilita mantenerse sincronizado cuando se produzcan cambios en nuestras comprobaciones de código.
Tenga en cuenta que, si es necesario, puede omitir estas verificaciones usando el comando git commit --no-verify.
Si no desea incluir pre-commit como parte de su flujo de trabajo, aún puede ejecutar el siguiente comando para usarlo como verificación:
pre-commit run --files <files you have modified>
sin necesidad de ejecutar pre-commit install de antemano.
Si desea ejecutar una revisión en todos los archivos enviados recientemente, puede usar el siguiente comando:
pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files
sin necesidad de ejecutar pre-commit install de antemano.
Nota
Puede considerar ejecutar periódicamente el comando pre-commit gc para limpiar los repositorios que ya no se utilizan.
Compatibilidad hacia atrás#
Mantén la compatibilidad hacia atrás tanto como sea posible. Si consideras que un cambio es necesario, explica claramente los motivos en la solicitud de extracción (pull request). Asimismo, ten cuidado al modificar las firmas de métodos y agrega advertencias de obsolescencia cuando sea necesario. Además, añade la directiva de Sphinx para funciones o métodos obsoletos.
También necesitas
Escribe un nuevo caso de prueba que emita una advertencia al llamar con parámetros obsoletos.
Actualiza todos los casos de prueba y el código existentes de Xinference para utilizar los nuevos parámetros.
Tipo de sugerencia#
Xinference recomienda encarecidamente el uso de sugerencias de tipo al estilo PEP 484. El nuevo desarrollo debe incluir sugerencias de tipo, ¡y las solicitudes de extracción que añadan anotaciones a código existente también son bienvenidas!
Desarrollo guiado por pruebas#
Xinfeference valora mucho las pruebas y alienta firmemente a los contribuyentes a adoptar el desarrollo guiado por pruebas (TDD). Este proceso de desarrollo «depende de la repetición de ciclos de desarrollo muy cortos: primero, el desarrollador escribe un caso de prueba automatizado (inicialmente fallido) para definir la mejora o nueva funcionalidad deseada, y luego utiliza el código mínimo para superar dicha prueba». Por lo tanto, antes de escribir cualquier código, debe redactar sus casos de prueba. Generalmente, los casos de prueba pueden obtenerse del problema original en GitHub. Sin embargo, vale la pena considerar situaciones adicionales y escribir los casos de prueba correspondientes.
Después de enviar el código a Xinference, a menudo se pide agregar ejemplos de prueba. Por lo tanto, es muy importante desarrollar el hábito de escribir ejemplos de prueba con anticipación, para que no surjan problemas.