How To Create Amazing Open Source Modules github.com/ kumar303/ build-open-source

Newbies or seasoned hackers

Topics:

• scaffolding that works today
• essential tools
• docs
• stability
• community

Mozilla <3 open source

Mozilla: 45+ Django modules

• django-aesfield
• django-browserid
• django-cache-machine
• django-memcached-pool
• django-nose
• django-paranoia
• django-statsd
• django-waffle

Useless modules are OK

Open by default

I want to use your module

When should you create a module?

NIH is a disease. Get help

TODO: liberate

from distutils.core import setup

setup(name='yourmodule',
      version='1.0.0',
      ...)

from setuptools import (setup,
                        find_packages)

setup(name='yourmodule',
      packages=find_packages(exclude=['tests']),
      ...)

Publish to PyPI

python setup.py sdist \
                register \
                upload

pip install yourmodule

34,347 packages

yourmodule/__init__.py:

__version__ = '1.0.0'

import re, sys

version = None
for line in open("./yourmodule/__init__.py"):
    m = re.search("__version__\s*=\s*(.*)", line)
    if m:
        version = m.group(1).strip()[1:-1]
        break
assert version

setup(...,
      classifiers=[
        'Programming Language :: Python :: 2',
        'Programming Language :: Python :: 3',
      ])

Support Python 2 and 3 with six

Use check-manifest to validate MANIFEST.in

setup.cfg will solve all your problems (I think)

setup(...,
      license='Apache 2')

WTFPL - Do What the Fuck You Want to Public License

Write documentation (it's ok to be lazy)

Add a README.rst file

Say anything in the README, just say something

Crucial docs:

1. what your module does
2. how to install it
3. how to use it
4. how to hack on it

When you are AWESOME:

• switch to Sphinx
  • README.rst converts nicely
• deploy to readthedocs.org from git

Usage docs:

• show code, examples
• use doctest (but be careful)
• document settings

.. doctest::
    :hide:

    >>> fudge.clear()

.. doctest::

    >>> from fudge import Fake
    >>> do_login = Fake()

Do not hide import paths. Thx.

def login(user, passwd):
    """
    Logs in the user

    :param user: string
    :param passwd: string
    :rtype: boolean
    """

.. autofunction:: yourmodule.login

Tell a story about your module. Fallback to the API reference.

Newbies vs. power users

How to test...

• test environment
• running tests
• running partial tests

Nice docs:

• where to get help
• changelog
  • backwards incompatible
  • migration guide
• roadmap?

Use tox to test your module

[testenv]
commands=
    python manage.py test

[testenv:py27]
basepython=python2.7

[testenv:py32]
basepython=python3.2

[django14]
deps=
    Django >= 1.4, < 1.5

[django15]
deps=
    Django >= 1.5, < 1.6

[base]
deps=
    M2Crypto >= 0.21.1

[django14]
deps=
    Django >= 1.4, < 1.5
    {[base]deps}

Run tests continuously with TravisCI

language: python
python:
  - "2.7"

install:
  - pip install tox
script: tox

Accepting patches

• choose your criteria
  • require tests
  • require docs
  • review patches

Open source governance

• meritocracy
• experts emerge
• contributors come and go

Bikeshedding

• don't let it slow you down
• working code trumps all

Maintenance?!

• chores, release management
• quit at will
• maintain modules you care about

How did Ian Bicking do it?

"I have no idea ..."

Ian says...

• low quality project, more engagement
  • pip needed a lot of work
  • release early
• if the module is useful ... ?
• appreciate and empower others

That's it

• make amazing modules
  • try to patch other modules first
• questions?
• @kumar303