Everything you wanted to know about Lyntin development

This page covers how to contribute to Lyntin, our coding conventions, contributors and ends with various processes that we use.

If you plan on helping out Lyntin development, you should read this guide in its entirety and also read through the FAQ which covers a lot of issues as well.

This guide is a draft and can change at any time--we update it as necessary.

How to contribute

Send diffs and code patches to the lyntin-devl mailing list and they will be analysed, and (possibly) factored into the code base. All contributions are much appreciated even if they are not used. Generally the only time something doesn't make it into the codebase is if I figure out a better way to do it, it doesn't coincide with Lyntin's mission or it raises an issue I hadn't thought about and want to mull over.

Other ways to contribute involve downloading Lyntin and using it lots. Find bugs, think of things that should be added, find flaws in the documentation, contribute tutorials and howtos for the repository, etc etc etc.

If you're using code that's in CVS, report bugs to the lyntin-devl mailing list. Post bugs regarding released versions to the bug tracker.

Lyntin has dynamically loading modules allowing you to fully encapsulate new functionality in a module file that you can distribute as an independent component. I highly encourage people to build new functionality into modules and distribute them as you see fit. Let me know and I'll add links to the Lyntin site to your modules. If you have problems building a module because a necessary component to the API is missing, let us know and we'll either help you around the problem, or adjust the API.

If you want to help with Lyntin development and want to take on a task, check out the todo section of our roadmap. I try to flesh out details there as time goes on. Tasks that have already been assigned to people are noted as such. If something isn't in the roadmap that you think should be--let us know!

Note: for code and patches to be accepted into the code base, you must either declaim your copyright over the code or assign the copyright to the FSF.

As a form of appreciation, contributors are listed here and as output to the #wizlist command.

Contributors to Lyntin

Lyntin has been helped along by many hands. This is a (non-exhaustive) list of folks who have contributed to Lyntin's development. (If you want your name added/adjusted/removed/whatever, let me know.) The list is in no particular order.

Lyn A Headley, Will Guaraldi, Aquarius, James, Sebastian John, Joshua Berne, Brian Bell, William Shaer, George Thompson, Brian Muir, GlassSnake, Conan Brink, and Malachi Clark.

Coding Style Guide

This document describes Lyntin coding conventions and development processes.

Tabstops and spacing

Indentation is done in multiples of 2. All spacing shall be done with spaces--no tabs. Indent when you need to per Python syntax.

Maximum line length

Maximum line length should be 80 characters--though you should seriously consider breaking up lines between 70 and 80 characters long to make it easier to deal with.

From Guido's Style Guide:

   The preferred way of wrapping long lines is by using
   Python's implied line continuation inside parentheses,
   brackets, and braces.  If necessary, you can add an
   extra pair of parentheses around an expression, but
   sometimes using a backslash looks better.  Make sure
   to indent the continued line appropriately, ...

Some examples (ed. adjusted by Will):

   class Rectangle(Blob):
   
     def__init__(self, width, height, color='black', 
                 emphasis=None, highlight=0):
       if width == 0 and height == 0 and \
             color == 'red' and emphasis == 'strong' or \
             highlight > 100:
         raise ValueError, "sorry, you lose"

       if width == 0 and height == 0 and (color == 'red' or
                                             emphasis is None):
         raise ValueError, "lose again!"

       Blob.__init__(self, width, height, color, emphasis,
                     highlight)

Naming

File, module, and package names are all lowercase with no punctuation except underscores:

• threadmanager.py
• engine.py
• ticker.py
• _user.py

Constants are all uppercase with _ between words:

• ESC
• ANSI_TEXT_REGEXP
• _BLUE

Classnames are mixed case starting with an uppercase letter:

• Engine
• SocketCommunicator
• ThreadManager

Methods are mixed case with the first letter being lowercased:

• handleMethod
• isDigit

Functions and variables are all lowercase with underscores:

• variable_one
• var2

Comments

There are three mortal sins regarding comments:

1. code with no comments
   Punishable by death--unless your code is so unbelievably good that it reads like English. Even then it should be commented.
2. comments that are poorly written
   Comments should be written in English and should be either well-formed sentences or well-formed phrases. They should be informative--not reduntant. They should be poetic--revel in your commenting.
3. comments should not contradict the code
   This usually happens when you change the code but forget to change the comment. VERY BAD. Always check comments around code you're editing and adjust them accordingly.

Docstrings

All modules, classes, functions, and methods should have doc strings. We run an out of line documentation generater against these doc strings and thus they become part of the online html documentation of the code. They help us--they make it easier to look things up and to understand what the code does. Docstrings should be terse, informative, and beneficial. They should answer the questions:

1. What is this?
2. How do I use it?
3. What does it take in as input and return as output?

Docstrings are denoted by the use of """ around the docstring. Anything else is just a regular comment or string. Docstrings should be sentences--not phrases.

Docstrings should be written in Epytext (http://epydoc.sourceforge.net/) which is a simple markup that has some characteristics found in Javadoc. We generate our API documentation from the docstrings and having it in the right format makes prevents me from going in and fixing it later.

Docstrings for functions and methods should denote the types and descriptions of any arguments passed in and any return values.

Examples of docstrings:

   def getCount(self):
      """
      Returns the number of aliases this manager has.

      @returns: the number of aliases contained
      @rtype: int
      """
      return len(self._aliases)

   def addAlias(self, alias):
      """
      Adds an alias.

      @param alias: the alias to add consisting of a tuple of
          the key and the expansion strings
      @type  alias: (string, string)
      """
      self._aliases[alias[0]] = alias[1]

Release Process for Lyntin 4.0

1. change the version number
2. generate README and COMMANDS and copy them over
3. make changelog and then fix the Changelog to only include changes since the last release
4. make epydoc to generate the API documentation
5. python setup.py sdist
6. python setup.py bdist_wininst
   
7. log into SourceForge
8. go to Lyntin admin "edit/release files"
9. click on "add release" for lyntin
10. release name is "lyntin 4.0" of the lyntin package
11. do that release thing
    
    
12. add blog entry
13. adjust the roadmap
14. copy everything up to the website
15. announcement on Freshmeat
16. write up a SourceForge news item
17. update the Vaults of Parnassus
18. announcement on lyntin-devl