[Freeipa-devel] Introducing the freeIPA v2 source tree

[Jason Gerard DeRose]

The experimental freeIPA v2 branch is now available!

NOTE: This is NOT the release of freeIPA 2.0! This is only a highly
experimental, incomplete, and unstable work-in-progress! Do not use this
code in production yet!

Details follow, but for the impatient, you can checkout the code with
this command:

  git clone git://fedorapeople.org/~jderose/freeipa2.git

And the new API documentation can be found here:

  http://jderose.fedorapeople.org/freeipa2-dev-doc/

Some of this initial development was done behind closed doors, for which
I personally apologize. The initial plugin work started as my personal
doodling and brainstorming, and then ended up being our v2 code base.
Between this and the fact that we are all very busy here, I didn't get
this work out into the community as quickly as I should have.


======================
Overview of what's new
======================

For v2 we have done a substantial refactoring of the underlying Python
code to eliminate code redundancy and to utilize fully the rapid
development capabilities of Python. This was rather desperately needed
to keep the code manageable as we add the huge increase in functionality
planned for v2.

These are the goals of the refactoring, all of which have been met:

1. Implement a pluggable architecture. In v2, all major functionality is
pluggable, and it's trivial to add new classes of pluggable
functionality. There is now a single VCS-style "ipa" script where the
first argument is the command name (and where each command corresponds
to a command plugin). The pluggable architecture was inspired by Bazaar.

2. Eliminate the code duplication present in v1. This has been fixed by
the design of the v2 pluggable architecture.

3. Make it easy to run and to test from within the source tree. All of
the Python packages are now located in the root of the source tree,
allowing one Python package to import another. For one, this allows you
to run freeIPA entirely from the source tree, meaning you no longer need
to build the distribution package to experiment with certain changes.
For another, this change was required to make it easy (or sometimes just
possible) to write unit tests, particularly if the test involved
multiple Python packages.

Currently the v2 code has more-or-less all the v1 functionality minus
the installation script and web-UI. One notable new addition in v2 (at
this early stage) is automount support. Obviously many more features
will be added before the stable 2.0 release is made.

The easiest way to experiment with v2 is to first install v1 so that
LDAP and Kerberos get configured correctly. Then v2 can be installed in
parallel with v1, or simply run from its source tree. To get a list of
the available commands, run the "ipa" script with no command, like this:

  ./ipa


===================
Python coding style
===================

For v2, we now officially have a Python coding style.

Although Python's syntax enforces quite a lot of stylistic consistency,
there is still much wiggle room, so a style guide will help keep us
productive and happy.

Fortunately, thanks to the "Benevolent Dictator For Life" (Guido van
Rossum, the author of Python), there is only one coding style for
Python, which is defined in PEP-8 and PEP-257.

PEP 8 -- Style Guide for Python Code:

  http://www.python.org/dev/peps/pep-0008

PEP 257 -- Docstring Conventions:

  http://www.python.org/dev/peps/pep-0257


======================
Unit testing with nose
======================

For v2, all the Python unit testing is being done using nose:

  http://somethingaboutorange.com/mrl/projects/nose/

nose was chosen because it allows unit tests to be written very quickly
and in a quite natural and flexible manner.

All the unit tests are located in the tests/ directory in the source tree.


=======================================
API documentation generated with epydoc
=======================================

For v2 we are generating API documentation using the epydoc tool:

  http://epydoc.sourceforge.net

The API documentation is currently available here:

  http://freeipa.org/developer-docs/

And a tutorial for plugin writers is available here:

  http://jderose.fedorapeople.org/freeipa2-dev-doc/ipalib-module.html

We are using reStructuredText markup in the docstrings, which you can
read about here:

  http://docutils.sourceforge.net/rst.html

The epydoc generated documentation is an excellent way to learn the v2
code base, particularly because all the cross-references are
hyper-linked. I'm personally making a big effort to include lots of
example code in the docstrings for the core v2 library. All these
examples are automatically tested using the Python doctest module:

  http://docs.python.org/library/doctest.html

We are relying on nose to automatically discover all the code examples
and then to test them with doctest. This is done using the
--with-doctest option, like this:

  nosetests --with-doctest


================
Getting involved
================

We certainly welcome comments, ideas, code, documentation, etc. See the
"Contribute" page on freeIPA.org:

  http://freeipa.org/page/Contribute

If you have questions or comments about the v2 plugin architecture, feel
free to ping me (jderose) on the #freeipa-devel IRC channel on freenode.net.










-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 835 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20081110/d690cb6d/attachment.sig>