Categorías
Python

Cómo sacar el máximo provecho de PyCon

 

Tabla de Contenidos

  • Proyecto LayoutLicensingREADMEContributing Guidelinessetup.py
  • Licensing
  • README
  • Contribuir Directrices
  • setup.py
  • GitHubHandling Tire RequestsVersioning, ramificación, y los lanzamientos
  • Tire el manejo de solicitudes
  • de versiones, ramificación, y liberaciones
  • Documentación
  • Automatizar el código de calidad
  • Colaboración vs Cooperación
  • Resumen
  • Licensing
  • README
  • Contribuir Directrices
  • setup.py Tire Manejo
  • Pide
  • de versiones, ramificación, y los lanzamientos

Este es un puesto de invitado por Patrick Altman, un apasionado pirata informático de código abierto, y vicepresidente de ingeniería en Eldarion.

En este artículo vamos a diseccionar una aplicación de Django repetitivo destinado a desarrollar rápidamente proyectos de código abierto que se adhieren a las convenciones ampliamente compartidos.

La disposición (o patrón) que vamos a estar viendo se basa en django-Raya-pagos. En este diseño se ha probado con éxito por más de 100 proyectos de código abierto diferentes publicados por Eldarion y Pinax.

a medida que avanza a través de este artículo, tenga en cuenta que su proyecto específico puede variar de este patrón; Sin embargo, hay una serie de elementos que son bastante comunes entre los proyectos de Python, y para algunos proyectos de código abierto de titulación en general. Nos centraremos en estos artículos.

Proyecto Disposición

Un diseño de proyecto de buena ayuda a un nuevo usuario navegar por su código fuente. Hay ciertas convenciones que son comúnmente aceptadas, así que son importantes para acatar. Además, un buen diseño de proyecto ayuda con el empaquetado. diseños

Proyecto

diferirán un poco dependiendo de si son paquetes de Python (como una aplicación Django reutilizable) o algo así como un proyecto de Django. Utilizando nuestro proyecto de ejemplo, nos gustaría destacar algunos aspectos del diseño, así como los archivos incluidos en el nivel superior del proyecto.

Debe reservar la raíz de su proyecto para los archivos de metadatos que describen diversos aspectos de su proyecto, como una licencia, CONTRIBUTING.md, README.rst, así como las secuencias de comandos para ejecutar pruebas y embalajes. Además, debe haber una carpeta en este nivel de la raíz que se llama lo que quiere el nombre del paquete de Python que sea. En nuestro ejemplo django-Raya-pagos es pagos. Por último, debe almacenar la documentación como un proyecto basado Sphinx en una carpeta llamada docs.

Licensing

En general, es mejor para licenciar su software en el MIT permisiva o licencias BSD si su objetivo es la adopción más extendida posible. Cuanto mayor es la adopción, la mayor exposición en entornos del mundo real variaron que aumenta la oportunidad para la retroalimentación y la cooperación a través de solicitudes de extracción. Almacenar el contenido de la licencia en un archivo de licencia en la raíz de su proyecto.

README

Cada proyecto debe tener un archivo README.rst en la raíz del proyecto. En este documento se debe presentar brevemente el usuario al proyecto, describir lo que resuelve un problema, y ​​proporcionar una rápida guía de introducción.

Nombre que README.rst y lo puso en la raíz de tu repositorio GitHub y la mostrará en la página principal del proyecto para los usuarios potenciales para ver y hojear a través de obtener una idea rápida de cómo el software puede ayudar a ellos.

Usando reStructuredText en lugar de Markdown en el readme se recomienda para que muestre muy bien en PyPI si publica su paquete.

Contribuir archivo Directrices

Un CONTRIBUTING.md analiza el libro de estilo de código, los procesos y directrices para las personas que deseen contribuir código a través de solicitudes de tiro para su proyecto. Esto es útil en la reducción de la barrera para las personas que deseen contribuir código. contribuyentes de primera vez pueden estar nervioso acerca de hacer algo mal o fuera de convenciones y el más detallado de este documento es más se puede comprobar a sí mismos sin tener que hacer preguntas que pudieran ser demasiado tímido para preguntar.

setup.py

Un buen empaque ayuda a la distribución de su proyecto. Al escribir un script setup.py, puede aprovechar utilidades de paquetes de Python para crear y publicar su proyecto en PyPI.

Este es un script muy simple. Por ejemplo, aquí está el núcleo del guión de django-Raya-pagos:

PACKAGE = "payments"
NAME = "django-stripe-payments"
DESCRIPTION = "a payments Django app for Stripe"
AUTHOR = "Patrick Altman"
AUTHOR_EMAIL = "paltman@eldarion.com"
URL = "https://github.com/eldarion/django-stripe-payments"
VERSION = __import__(PACKAGE).__version__

setup(
    name=NAME,
    version=VERSION,
    description=DESCRIPTION,
    long_description=read("README.rst"),
    author=AUTHOR,
    author_email=AUTHOR_EMAIL,
    license="BSD",
    url=URL,
    packages=find_packages(exclude=["tests.*", "tests"]),
    package_data=find_package_data(PACKAGE, only_in_packages=False),
    classifiers=[
        "Development Status :: 3 - Alpha",
        "Environment :: Web Environment",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: BSD License",
        "Operating System :: OS Independent",
        "Programming Language :: Python",
        "Framework :: Django",
    ],
    install_requires=[
        "django-jsonfield>=0.8",
        "stripe>=1.7.9",
        "django>=1.4",
        "pytz"
    ],
    zip_safe=False
)

Hay varias cosas que suceden aquí. Recuerda que hemos discutido haciendo el archivo reStructuredText README.rst?

Eso se debe a que como se puede ver por la long_description estamos utilizando el contenido de ese archivo para poblar la página de destino en PyPI y ese es el lenguaje de marcas utilizado allí. Los clasificadores son un conjunto de metadatos que ayuda a poner su proyecto en las categorías adecuadas en PyPI.

Por último, el argumento install_requires se asegurará de que cuando el paquete está instalado que estas dependencias enumeradas se instalan o que ya están instalados.

GitHub

Si el proyecto no está en GitHub que están realmente desaparecidas. Seguro que hay otros DVCS basada en Web (sistema distribuido de control de versiones) sitios que ofrecen alojamiento gratuito de código abierto, pero ninguno ha hecho más por la fuente abierta que GitHub.

Manipulación y jalar solicitudes

parte de la construcción de un gran proyecto de código abierto está haciendo más grande que uno mismo. Esto implica no sólo aumentar simplemente la base de usuarios, sino también la base de contribuyentes. GitHub (y git en general) realmente ha transformado cómo se hace esto.

Una clave para el aumento de contribuyentes es responder en la gestión de las solicitudes de extracción. Esto no significa aceptar todas las contribuciones, pero también permanecen abiertas las respuestas de mentalidad y mango con la deferencia que le gustaría recibir si contribuían a otro proyecto.

No sólo cerca de las solicitudes que no desee, pero toma el tiempo para explicar por qué no se acepta, o si es posible explicar cómo se pueden mejorar para que puedan ser exceptuados. Si las mejoras son menores o que de lo contrario se pueden mejorar por sí mismo, seguir adelante y aceptarlo y luego hacer las correcciones que le gustaría. Hay una línea muy fina entre pedir mejoras en comparación con sólo les hace a sí mismo.

El principio rector es crear un ambiente acogedor y agradecido. Recuerde que sus colaboradores están ofreciendo su tiempo y energía para mejorar su proyecto.

versiones, la ramificación, y los lanzamientos

Lea y siga semántica de versiones al crear versiones.

Al hacer grandes lanzamientos siempre documentar cambios incompatibles con claridad hacia atrás. Es más fácil si el documento cambia a medida que los está cometiendo mediante la actualización de un archivo de registro de cambios a medida que trabaja entre versiones. Este archivo podría ser simplemente un fichero de cambios en la raíz de su proyecto, o parte de su documentación en un archivo en algún lugar como docs / changelog.rst. Esto le permitirá crear agradables notas de la versión con muy poco esfuerzo.

mantener estable al maestro. Siempre existe la posibilidad de que la gente va a usar el código maestro en lugar de un comunicado de paquetes. Crear ramas de características para el trabajo y de mezcla cuando se probó y relativamente estable.

Documentación

Ningún proyecto es totalmente completa hasta que hay una cierta cantidad de documentación. Una buena documentación ahorra a los usuarios de tener que leer el código fuente para determinar cómo utilizar el software. Una buena documentación comunica que se preocupa por sus usuarios.

Con Leer la documentación, que puede tener la documentación de renderizado y alojado de forma gratuita de forma automática. Se actualizará automáticamente en cada confirmación de dominar que es super cool.

Para utilizar Leer los documentos, se debe crear un proyecto de documentación basada en la documentación Sphinx carpeta en la raíz de su proyecto. Esto realmente es una cosa bastante simple y consiste en un Makefile y un archivo conf.py y luego una colección de archivos reStructuredText formateado. Esto se puede hacer de forma manual copiando y pegando el archivo Makefile y conf.py de un proyecto anterior y la modificación de los valores, o ejecutando:

$ pip install Sphinx
$ sphinx-quickstart

Código Automatización de Calidad

Hay una serie de herramientas que puede utilizar para ayudar a la calidad torreón bajo control de sus proyectos. Pelusa, pruebas y cobertura de las pruebas de todo debe ser utilizado para ayudar a asegurar la calidad no se mueve durante la vida del proyecto.

de inicio con pelusa con algo como pylint o pyflakes o PEP8. Todos ellos tienen sus ventajas y desventajas, que están más allá del alcance de este artículo para explorar. Punto es: estilo coherente es el primer paso de un proyecto de alta calidad. Además, ayudando con el estilo de estos borra de pueden ayudar a identificar algunos errores simples rápidamente.

Por ejemplo, para django-Raya-pagos, tenemos un guión que combina dos herramientas que ejecutan diferentes pelusa con excepciones personalizadas para nuestro proyecto:

# lint.sh
pylint --rcfile=.pylintrc payments && pep8 --ignore=E501 payments

Tome un vistazo al archivo .pylintrc en los django-Raya-pagos para el reporto ejemplos de algunas de las excepciones. Una cosa acerca de pylint es que es bastante agresivo y puede ser ruidoso con las cosas son que realmente no son problemáticos. Es necesario decidir por sí mismo para ajustar su propio archivo .pylintrc pero recomienda la documentación y el archivo para que sepa más adelante por qué se está excluyendo ciertas reglas.

Configuración de una buena infraestructura de la prueba es importante para demostrar que sus obras de código. Por otra parte, escribiendo algunas de sus pruebas de primera puede ayudar a pensar a través de su API. Incluso si usted escribe pruebas último, el acto de escribir pruebas expondrá puntos débiles en el diseño de su API y / u otros problemas de usabilidad que se pueden abordar antes de que se informa.

Parte de su infraestructura de pruebas debe implicar el uso de coverage.py para mantener un ojo en la cobertura de un módulo. Esta herramienta no le dirá si el código es probado, sólo usted puede hacer eso, sino que le ayudará a identificar el código que no se ejecuta en absoluto para que sepa qué código es definitivamente no se está probando.

Una vez que haya desprendimiento de fibras, scripts de pruebas y de cobertura integrado en su proyecto puede automatización de la configuración para que estas herramientas ejecutar en cada pulsación en una entornos más (por ejemplo, versiones diferentes de Python, diferentes versiones de Django, o ambos en una matriz de prueba) .

La creación de una integración Travis puede ejecutar pruebas de forma automática y borra de. Batas pueden ser añadidos a esta configuración para proporcionar la cobertura de la prueba histórica cuando Travis construye plazo. Ambos tienen características que le permiten incrustar una insignia en su README.md para mostrar estado más reciente construcción y cobertura.

Colaboración vs Cooperación

Durante DjangoCon 2011, David Eaves dio un discurso de apertura que elocuentemente en palabras la idea de que a pesar de la colaboración y la cooperación tienen definiciones similares, hay una sutil diferencia:

“Yo diría que la colaboración, la cooperación a diferencia , obliga a las partes involucradas en un proyecto a resolver los problemas de forma conjunta “.

Aleros va a dedicar un post entero específicamente a la forma en GitHub fue la fuerza motriz para la innovación cómo el código abierto funciona de forma específica, el aspecto de la gestión de la comunidad. En “Cómo GitHub guardadas Open Source” (ver Recursos), Alero afirma:

“Creo proyectos de código abierto funcionan mejor cuando los colaboradores son capaces de participar en la cooperación de bajo costo de transacción y colaboración elevado coste de transacción se reduce al mínimo. El genio de código abierto es que no requiere un grupo de debatir todos los temas y trabajar en forma colectiva los problemas, sino todo lo contrario “.

Él va a hablar sobre el valor de bifurcación y cómo se reduce el alto costo de la colaboración al permitir la cooperación bajo costo entre las personas capaces de asumir proyectos adelante sin permiso. Este se bifurcan empuja la necesidad de coordinación hasta soluciones están listas para ser fusionado en, lo que permite mucho más rápido y dinámico experimentación.

Puede dar forma a su proyecto de manera similar, con el mismo objetivo de aumentar la cooperación bajo costo y reducir al mínimo la colaboración cara a lo largo de la escritura, el mantenimiento y el apoyo a su proyecto siguiendo las convenciones y los patrones detallados en este post.

Resumen

Muchas estaba cubierto aquí con pequeños ejemplos reales. La mejor manera de aprender acerca de estas cosas en detalle es para navegar por los repositorios en GitHub de proyectos que hacen un buen trabajo en estos patrones.

Pinax tiene su propio repetitivo aquí, que puede ser utilizado para generar rápidamente un proyecto basado en las convenciones y los patrones que se encuentran en este post.

Tenga en cuenta, que incluso si vas con nuestra repetitivo o algún otro texto modelo, tendrá que encontrar un estilo en la ejecución de estas cosas que se ajuste a usted y su proyecto. Todas estas cosas son, además de escribir el código real de su proyecto, pero todos ayudan en el crecimiento de una comunidad de colaboradores.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *