Mike Looijmans wrote:
Inspired by our FieldStorage work with file uploads, I also made some
implementation changes to Field and StringField in util.py. In essense,
that will make things like using form['key'] multiple times much more
efficient. Also, FieldStorage will return the same object if called twice.
I'd like some feedback from the group on these changes, and also some
directions on what I'd need to do to get them integrated in the
mod_python beta. I have no experience whatsoever in contributing to open
source projects.
I think it's too late in the beta cycle to be rewriting code unless it's
to fix a specific, critical bug. We really, really, *really* need to
deliver 3.2 final, and I don't want to mess with working code at this
point. The changes you are suggesting are likely more appropriate for
3.3, or possibly a 3.2 bugfix release.
As far as contributing to mod_python, well, I think you already have the
right idea: propose changes; discuss on python-dev; seek consensus; wait
for your changes to be committed by myself or Nicolas. Bug fixes and
code improvements are much more likely to be accepted than major new
features. We want mod_python to be tightly focused on the core
functionality of providing a python interface to apache. The fancy bells
and whistles are best left to frameworks that utilize mod_python further
up the application stack.
For your specific changes, I would strongly suggest that you make your
changes against the mod_python development branch, ie trunk. Also people
are much more likely to test your changes if you submit a patch rather
than offering a completely new file. This makes it easier to see what
code is being changed and avoids problems with regressions.
I've put together a "Developer's Guide" draft that I'd like to
eventually see included in either the documentation or on the website.
This document doesn't represent any offical position of the mod_python
developers, but rather just what I see as best practices and some
resources for contributors. Everyone should feel free to offer
suggestions to improve this guide. The original is in svn at:
http://svn.apache.org/repos/asf/httpd/mod_python/branches/jgallacher/docs/developers-guide.rst
And no, I have not spell checked it yet. :)
Regards,
Jim
:version: $Id$
=============================================
Developer's Guide for mod_python Contributors
=============================================
Mod_Python is a subproject of the Apache `httpd server project`_.
As such we strive to conform to the practices recommended by the
`Apache Software Foundation`_.
.. _httpd server project: http://httpd.apache.org/
.. _Apache Software Foundation: http://www.apache.org/
Becoming a Developer
====================
A developer_ is a user who contributes to a project in the form of code or
documentation. They take extra steps to participate in a project, are active
on the developer mailing list, participate in discussions, provide patches,
documentation, suggestions, and criticism. Developers are also known as
contributors.
Contributions from developers are integrated into mod_python by committers_
at the committer's discretion.
*(Should we mention that everyone on python-dev gets a vote on releases? -jg)*
*(Should we mention that becoming a committer is by invitation only? -jg)*
See `ASF roles`_ for more information.
.. _developer: http://www.apache.org/foundation/how-it-works.html#developers
.. _committers: http://www.apache.org/foundation/how-it-works.html#committers
.. _ASF roles: http://www.apache.org/foundation/how-it-works.html#roles
Developer Mailing List
======================
Development issues such as patches, bug fixes, ideas, etc are discussed
on the python-dev mailing list. Subscribe to the python-dev@httpd.apache.org
list by mailing [EMAIL PROTECTED] This is a advanced
topic list for people who are versed in C and Apache httpd internals.
*(I borrowed this bit from the website. I think we could re-phrase this to
be a little less intimidating. People with good python skills but no knowledge
of apache internals or C can still make valuable contributions. -jg)*
Issue Tracking
==============
The mod_python project uses JIRA for `issue tracking`_. The best way to ensure
your improvements, suggestions or bug reports are not lost in the noise of the
mailing list is to create a new issue in JIRA. Likewise, if you have a patch
you want to submit it is best to attach it to the appropriate JIRA issue rather
than sending it to directly to the mailing list. The python-dev mailing list
automatically receives a message when a JIRA issue is created or modified so
you can be assured your issue will get noticed.
.. _issue tracking: http://issues.apache.org/jira/browse/MODPYTHON
Subversion Code Repository
==========================
The mod_python project uses Subversion for version control. You can browse_
the repository online. For more help on using Subversion, consult the
`Subversion website`_ or
the `Subversion book`_. The web site provides a list of `clients and useful
links`_.
.. _browse: http://svn.apache.org/viewcvs.cgi/httpd/mod_python/
.. _Subversion website: http://subversion.tigris.org/
.. _Subversion book: http://svnbook.red-bean.com/
.. _clients and useful links: http://subversion.tigris.org/project_links.html
Anonymous Subversion Checkout
-----------------------------
To access the Subversion repositories anonymously, you will need a Subversion
client.
Choose the branch you would like to work on and check it out. For example,
to get the current development branch (trunk), use::
svn co http://svn.apache.org/repos/asf/httpd/mod_python/trunk mod_python
Subversion Commit Notifications
-------------------------------
Subversion commit notifications are available on the python-cvs mailing list.
Subscribe to the [EMAIL PROTECTED] mailing list by mailing
[EMAIL PROTECTED]
Writing Code
============
You should develop your code using the working copy of mod_python you checked
out with Subversion.
Coding Style
------------
Python
......
Indent your code with 4 spaces.
*(Let's expand this section with some good general recommendations. -jg)*
C Language
..........
For C-language coding style, follow the `Apache Developers' C Language Style
Guide`_.
.. _Apache Developers' C Language Style Guide:
http://www.apache.org/dev/styleguide.html
Comments
........
As per the Apache style guide, use only C-style comments in your C-code.
Do not use C++ style comments.
Use the Doxygen format for comments.
*(I'll add a quick and dirty guide to doxygen. -jg)*
Unit Tests
==========
We like unit tests. Get in the habit of running the tests when you modify some
code. Likewise it's very helpful if you can write unit tests for your new code.
*(Maybe stick a simple example explaining how to write a unit test here? -jg)*
Documentation
=============
Ideally you'll provide documentation for your code as a patch to the current
docs. However, if you don't feel comfortable writing LaTex code feel
free to write in plain text. Heck, we'll accept good documentation in just
about any format.
Preparing Your Code For Submission
==================================
The preferred form for submitted code is as a patch created as a diff against
the current development branch. The diffs should be in the unified diff
format. Luckily, Subversion makes this easy. To create a patch for
changes made to src/util.c use svn diff::
svn diff src/util.c > jg-20051114.diff
Choose a reasonable name for your patch. Files attached to a JIRA issue
are sorted alphabetically and listed at the top of the JIRA page for that
issue. It'll make it easier to understand what has been uploaded if you
adopt a consistent naming scheme.
*(Perhaps we can agree on a naming scheme that contributors would be
urged to adopt. Take a look at `MODPYTHON-77`_ to see why this is desirable.)*
.. _MODPYTHON-77: http://issues.apache.org/jira/browse/MODPYTHON-77
License
=======
As with all Apache Software Foundation projects, mod_python is licensed under
the current `Apache Software License (ASL)`_, `Version 2.0`_.
.. _Apache Software License (ASL): http://www.apache.org/licenses
.. _Version 2.0: http://www.apache.org/licenses/LICENSE-2.0.html
