Differences

This shows you the differences between two versions of the page.

--- devel:hacking [2009/02/09 10:15]
morten pasted in NAV's HACKING file.
+++ devel:hacking [2013/06/19 07:45]
morten fix jenkins url
@@ Line 1: / Line 1: @@
-=======================
+====== Hacker's guide to NAV ======
- Hacker's guide to NAV
-=======================
 If you are contributing code to Network Administration Visualized,
@@ Line 7: / Line 5: @@
-Participating in the community
+====== Contributing to NAV ======
-==============================
 Originally, NAV was a closed source project, initiated by the
 Norwegian University of Science and Technology (NTNU), and eventually
 sponsored by UNINETT on behalf of the Norwegian higher education
 community.  In 2004, however, NTNU and UNINETT started distributing
-NAV under the GNU General Public License, making it a true open source
+NAV under the GNU General Public License, making it a truly free
-project.
+software system.
-While NTNU and UNINETT still are the main contributors to NAV,
+While UNINETT and NTNU are still the main contributors to NAV,
 developing NAV to support the needs of the Norwegian higher education
-community, volunteer work from other interested parties is highly
+community, contributions from third parties is highly appreciated.
-appreciated.
-The community exists mainly through mailing lists, a wiki and a
+We communicate mainly through mailing lists,
-Subversion repository, although UNINETT also arranges seminars and
+[[https://launchpad.net/nav/|Launchpad]] and the ''#nav'' IRC channel
-gatherings for its target audience: Norwegian universities and
+on //FreeNode//.  At times, UNINETT also arranges workshops and
-university colleges.  To participate:
+gatherings for its customers: Norwegian universities, university
+colleges and research institutions.
-Go to http://metanav.uninett.no/ and
+To contribute:
-* Join the mailing lists.  The nav-dev mailing list in particular is
+Go to http://nav.uninett.no/ and
-  for discussing NAV development.  So far, this is a low traffic list.
-  We can only hope this will change ;-)
-* Get a copy of the latest development sources from
+  * Join the mailing lists.  The //nav-dev// mailing list in
-  https://svn.itea.ntnu.no/repos/nav/navme/trunk/. New development
+    particular is for discussing NAV development.  So far, this is a
-  always takes place on trunk. Bugfixes, enhancements, and new
+    low traffic list. We can only hope this will change ;-)
-  features are backported from there to the various release branches.
+  * Get a copy of the latest development sources by cloning the
+    Mercurial repository at http://nav.uninett.no/hg/default/.
+    Most new development takes place on this branch.
+  * Take a look at the [[:navprojects|project reports from previous
+    development projects at NTNU]] (NAVMe, NAVMore, tigaNAV and
+    others) - design specifications and other useful bits of historic
+    NAV information is mostly to be found in these.  Unfortunately,
+    some of the oldest project documentation is in Norwegian only.  Do
+    not hesitate to ask for help on the mailing lists.
-* Take a look at the project reports from previous development
+If you wish to contribute code to the project, see the [[#submitting patches]] section.
-  projects at NTNU (NAVMe, NAVMore, tigaNAV and others) - design
-  specifications and other useful bits of historic NAV information is
-  mostly to be found in these.  Unfortunately, some of the older
-  project documentation is in Norwegian only.  Do not hesitate to ask
-  for help on the mailing lists.
-If you wish to contribute code to the project, please tell us about it
+====== Directory layout ======
-on the nav-dev mailing list.  It is always a good idea to check if
+A rough guide to the source tree:
-someone is already working on something similar, and to get some
-helpful tips on how to integrate your code with the rest of the
-project.  If you already went ahead and wrote a patch, announce it on
-nav-dev and provide a link to the patch so it can be studied for
-possible inclusion into NAV.
+| bin/       | NAV 'binaries'; executable scripts and programs. |
+| contrib/   | User contributed NAV tools. NAV doesn't depend on these, and any maintenance of them is left up to the original developers.  We do not offer support for these tools. |
+| doc/       | User and developer documentation |
+| etc/       | Example/initial configuration files |
+| java/      | Java source code |
+| media/     | Static media such as CSS stylesheets, images and JavaScript to be served by a webserver |
+| packages/  | Stuff to help packaging NAV for various platforms, such as RedHat, CentOS, FreeBSD, Debian and soforth. Much of this is outdated today. |
+| python/    | Python source code |
+| sql/       | SQL schema definitions and installation/sync tools |
+| templates/ | Django HTML templates |
+| tests/     | Automated tests |
+| tools/     | Tool scripts for the build and release processes. |
-Directory layout
+====== Development languages and frameworks ======
-================
-A rough guide to the source tree:
-* conf/
+Historically, NAV was written using multiple programming languages
-  Files related to the autoconf build system.
+(Perl, Java, PHP and Python).  While this has had an unfortunate
+impact on integration and maintenance over the years, we've managed to
+reduce this to just Python and Java in later years. We have a
+long-term goal to rewrite the remaining Java backend code to Python.
-* doc/
+Currently (as of September 2012), NAV consists mostly of Python code,
-  User and developer documentation, SQL scripts and example NAV
+with one remaining backend systems written in Java (eventEngine).
-  configuration files.
-* tools/
+  * We will only accept new code written in Python (except when it
-  Tool scripts for the build process.
+    involves patches to the existing Java code).
+  * When you contribute additions to the web interface, use the Django framework.
-* contrib/
+If you wish to contribute something really useful that doesn't use
-  Stuff that works with NAV, but that NAV doesn't depend on, and that
+Python, we may consider including it in the //contrib// directory.
-  is maintained by individuals who may or may not participate in NAV
-  development.
-* packages/
+If **YOU** are willing to invest in porting some of the existing Java
-  Stuff to help packaging systems, like rpm and dpkg.
+code to Python, then you will be celebrated as a NAV hero!
-* src/
+====== Coding style ======
-  Source code to Java subsystems of NAV (still here for historic
+Much of the legacy NAV code was written without using any coding style
-  reasons).
+guidelines.  This has resulted in some chaotic combination of styles,
+which we hope to reduce in the future.  For new code, please follow
+these guidelines:
-* subsystem/
+  * For Java code, please refer to SUN's "Code conventions for the
-  Source code to the rest of NAV - a lot of Python. NAV is loosely
+    Java Programming Language": http://java.sun.com/docs/codeconv/
-  divided into subsystems, and each one of these has its own
+  * For Python code, please refer to PEP-8, "Style Guide for Python
-  subdirectory in here.
+    Code" http://www.python.org/doc/peps/pep-0008/
-* subsystem/lib-python/
+If you see violations of these guidelines, don't hesitate to fix them.
-  Python libraries & APIs.  Please check what's already there before
+If you fix file-wide indentation problems etc., please submit this as
-  you roll your own.
+a separate patch to make your other patches look clean and readable.
-* subsystem/lib-perl/
+===== Python boilerplate headers =====
-  Perl libraries & APIs.  Please check what's already there before you
+We will generally only accept code into NAV if it is licensed under
-  roll your own.
+GPL v2, but we may make individual exceptions for code licensed under
+compatible licenses.  Each Python source code file should contain the
+following boilerplate at the top:
-* subsystem/webfront/
+<code python>
-  Python libraries for the web interface and front-page handler
+#
-  modules for mod_python.
+# Copyright (C) 2008,2009 Somebody
+#
+# This file is part of Network Administration Visualized (NAV).
+#
+# NAV is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License version 2 as published by the Free
+# Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.  You should have received a copy of the GNU General Public
+# License along with NAV. If not, see <http://www.gnu.org/licenses/>.
+#
+</code>
+If a file uses non-ASCII characters, it **must** be encoded as UTF-8, and an
+encoding statement should be inserted at the top:
-Development languages
+<code python>
-=====================
+# -*- coding: utf-8 -*-
-For historic reasons, NAV today is made up of several programming
+</code>
-languages - these are Python, Java and Perl. Although this is
-unfortunate in many ways, no-one has been willing to invest in the
-time needed to rewrite stuff to reduce the number of languages.
-When contributing patches to existing code, or plugins to existing
+===== Javascript =====
-subsystems, use the language that subsystem was written in.
-When writing entirely new subsystems, the following rules apply:
+When writing javascript code try to focus on modules not pages. If the code is html-related, it should take selectors or objects as input and concern itself solely about those. This makes for much easier testing and reuse. And of course - write the tests first.
-* If your subsystem is a new tool for the web interface, use Python.
+When the module is done you write a controller for the page that plugs the needed plugins to the page elements. This should fail gracefully if the needed elements are not present.
-  The web interface is built using mod_python. Also, the integration with
-  Cricket uses Cricket's web front-end, which is Perl CGI.
-* If your subsystem is a new back-end tool/daemon, please use Python.
+NAVs javascript uses [[http://requirejs.org/|require.js]] - use this to create modules and specify dependencies.
-  The Python API created for NAV is more complete than for any of the
-  other languages, and you will receive a lot for free.  You may use
-  Perl if you absolutely abhor Python, but then you will be frowned
-  upon.
-If *YOU* are willing to invest in porting some of the existing code to
+Pro tip is to create ''require_config.dev.js'' in ''media/js/'' and add the following configuration to requirejs:
-Python, then you will be celebrated as a NAV hero!
+<code>require.urlArgs = "bust=" +  (new Date()).getTime();</code> This makes sure your not using cached resources in your browser when developing, which browsers loves to do! See [[http://requirejs.org/docs/api.html#config-urlArgs|config-urlArgs]] in requirejs documentation for «details». The ''require_config.dev.js'' is added in global HG ignore.
+==== Accessing resources with ajax requiring authentication ====
-Coding style
+As your authenticated session might have timed out due to idle (no activity), resources will return 500 Internal Error if you do not supply the important ''//X-NAV-AJAX//'' header on your ajax requests.
-============
-NAV has not previously bothered with having coding style guidelines.
-This has resulted in some chaotic combination of styles, which we hope
-to reduce in the future.  For new code, please follow these
-guidelines:
-* For Java code, please refer to SUN's "Code conventions for the Java
+So make sure to include the ''**X-NAV-AJAX**'' header so you will get proper HTTP response code in the reponse from your request.
-  Programming Language": http://java.sun.com/docs/codeconv/
-* For Python code, please refer to PEP-8, "Style Guide for Python
+NAV has a shortcut for fixing this in ''default.js'' (adds a function in the public namespace NAV) which attaches the required handlers for jQuery by doing:
-  Code" http://www.python.org/doc/peps/pep-0008/
+<code>NAV.addGlobalAjaxHandlers()</code>
-If you see violations of these guidelines, don't hesitate to report
+====== Database ======
-them and/or fix them :) If you fix file-wide indentation problems
+NAV uses PostgreSQL as its database backend.  Namespaces (schemas) are
-etc., please submit this as a separate patch to make your other
+employed to logically group tables and relations.  NAV versions prior
-patches look clean and readable.
+to 3.5 employed separate PostgreSQL databases instead of namespaces.
+The namespaces currently in use are:
-Database connections
+| ''manage''      | The core knowledge database of NAV, containing all sorts of information about the monitored IP Devices, events, alerts, network topology and machine tracking data. |
-====================
+| ''profiles''    | Contains NAV user accounts and groups, user preferences and alert profiles. |
-NOTE: The following is Python-specific, more info should be added for
+| ''logger''      | Anything related to NAV's syslog parser/browser system. |
-the other languages used in NAV.
+| ''arnold''      | The port detention system Arnold stores it's data here. |
+| ''radius''      | Radius accounting logs, updated directly by FreeRadius' PostgreSQL module. |
-The NAV database actually consists of four PostgreSQL databases
+===== Connecting to the database (Python) ====
-(although there are plans to merge them into a single database using
+==== Raw SQL ====
-PostgreSQL's support for schemas).  The databases are:
-* 'manage': The core knowledge database of NAV, containing all sorts
+To obtain a connection to the NAV database, use the API accordingly,
-  of information about the monitored IP Devices, events, alerts,
+e.g.:
-  network topology and machine tracking dta.
-* 'navprofiles': Contains NAV user accounts and groups, user
+<code python>
-  preferences and alert profiles.
+import nav.db
+# Get a connection to the NAV database
+connection = nav.db.getConnection('default')
+</code>
-* 'logger': Contains syslog entries collected by the syslog
+The above code will open a connection to NAV's database, or, if a
-  parser/browser system.
+previous connection with these parameters is already open, returns the
+already existing connection from a connection cache.
-* 'arnold': The port detention system Arnold stores it's data here.
+The ''default'' parameter is there for legacy reasons; it specifies
+the name of a subsystem.  The ''db.conf'' file allows configuration of
+separate database users for each subsystem (known as a ''script'' in
+''db.conf'') of NAV.  The default ''db.conf'' file specifies a
+database user for a subsystem called ''default'', and also specifies
+the same database user for all known subsystem names.  At present,
+using a subsystem name that is not configured in ''db.conf'' will cause ''nav.db.getConnection()'' to revert to using the ''default'' name.
-To obtain a connection to the NAV database, use the API accordingly,
+==== Django models ====
-e.g.:
+NAV 3.5 and on includes Django models for most database tables.  If no
+SQL magic is needed to perform your database voodoo, it is recommended
+that you use these models, located in the module ''nav.models''.  You
+do not need to explicitly establish a database connection to use these
+models, as Django takes care of all that.
+The models are defined in modules of the ''nav.models'' package.
+===== Changing the schema ====
+The baseline schema is located in ''sql/baseline'' - the ''syncdb.py'' script
+is responsible for running this when creating a new database. To make a schema
+change, you **do not** change the baseline, but go to the ''sql/changes''
+directory and create a new schema change script there.
+Schema change scripts as numbered, using the following pattern:
+  * ''sc.<major>.<minor>.<point>.sql''
+The ''<major>'' and ''<minor>'' numbers usually correspond to the major and
+minor number of the next NAV release.  The ''<point>'' number is a sequence id
+- pick the next free number when creating a schema change script.
+Remember these points when creating a schema change script:
+  * Create separate change scripts for unrelated schema changes.
+  * Remember to write SQL to //migrate// existing data, if necessary.
+  * Do not use transactional statements - the ''syncdb.py'' script will take
+    care of that.
+To apply your change scripts, just run ''syncdb.py''.  It will look inside the
+''schema_change_log'' table to see which change scripts have already been
+applied, and it will detect your new change script and apply this to the
+database.
+:!: When changing the schema, don't forget to update the Django models in the
+''nav.models'' package.  An integration test exists to verify that the Django
+models can at least be used to run proper SELECTs against the database.
+====== Legacy web code ======
+Legacy web code interfaces directly with
+[[http://www.modpython.org/|mod_python]], and uses
+[[http://www.cheetahtemplate.org/|Cheetah for HTML templating]].
+All Cheetah templates are located in the ''python/nav/web/templates''
+directory.
+===== Legacy database connections in web code =====
+Use the ''nav.db.getConnection()'' call to open or retrieve an
+existing database connection.  All NAV web modules share the same
+interpreter and namespace per Apache process, which also means that
+database connections will be shared between the modules running in
+each process.  Therefore, the following conventions apply for
+connections obtained from ''nav.db.getConnection()'':
+  * **Do not, under any circumstances**, retain references to a database
+    connection between client requests.  Make sure to retrieve a new
+    connection at the start of each request cycle - the API will cache
+    connections between requests, and will automagically re-open
+    broken connections.  As the connection is shared between several
+    modules, retained references may be invalid in the next request
+    cycle.
+  * **Do not explicitly close database connections.**  Although the API
+    will try to reopen any closed or broken connections, you create
+    extra overhead, and you don't play nice with the other web
+    modules.
+  * **The obtained connections will use an isolation level of //read
+    committed//**, i.e. no autocommits.  Be careful to commit the
+    current transaction if you modify any data.  A mod_python
+    ''cleanuphandler'' will try to automatically commit all open
+    transactions as the request cycle ends, but this may change
+    in the future, so you must not rely on it.
+  * **Do not change the isolation level of a connection** without
+    restoring it to its original value before the end of the request
+    cycle.
+===== The "death" of mod_python =====
+''mod_python'' is no longer under active development and has been
+placed in the Apache foundation's "Attic".  We do not accept new web
+tools that interface directly with ''mod_python''.
+We do, however, aim to refactor existing mod_python-interfacing code
+into working as Django views.  A few tips for such refactorings:
+  * Each ''mod_python'' handler in NAV mostly performs its own custom
+    URL parsing and view dispatch.  It's best to refactor this into a
+    Django URL configuration and separate view functions first.
+  * Usage of ''mod_python.utils.FieldStorage'' parse URI arguments
+    must be refactored to use the ''POST'', ''GET'' or ''REQUEST''
+    objects of a Django ''HttpRequest''. It's not that hard, as these
+    objects behave like dictionaries, much like the ''FieldStorage''
+    class does.
+  * Conversion from Cheetah to Django templates is not necessary to
+    refactor a mod_python handler into a Django view.  It is desirable
+    to do so in later refactorings, though.
+  * NAV's authentication and authorization scheme hooks into Apache's
+    request cycle using a ''mod_python'' ''headerparserhandler''. It
+    also adds session data as an attribute to the ''mod_python''
+    request object.  Once there are no tools left that interface
+    directly with ''mod_python'', the auth and session parts of NAV
+    must be refactored to work in a pure Django setting before NAV can
+    be free of its dependence on ''mod_python''.
+====== Writing new web code ======
+If you are writing a new web application / tool for NAV, please use
+the Django framework.  [[devel:django_introduction|Here's a quick
+primer on how Django integrates with legacy NAV]].
+====== Version Control ======
+NAV uses [[http://www.selenic.com/mercurial/|Mercurial]] for
+distributed version control.  Official repositories are located at
+http://nav.uninett.no/hg/ .
+===== Guide to the repository jungle =====
+The official repositories represent three types of branches
+==== Unstable (default) ====
+New, bleeding edge development occurs on the
+//[[http://nav.uninett.no/hg/default/|default]]// branch, which is
+considered unstable (although we try to always keep it buildable).
+==== Feature branches ====
+New features that take a while (and a lot of changesets) to implement
+and test will often be published as separate feature branches.  For
+all intents and purposes, the feature branches will look like the
+//default// branch with some added feature.  They will merge changes
+from the //default// branch regularly.  Once a feature is considered
+"ready", the feature branch will be merged onto the default branch.
+==== Stable (series) ====
+Once we are nearing a new series release of NAV (such as 3.5 or 3.6),
+a new [[http://nav.uninett.no/hg/series/|series branch]] is
+created from the //default// branch.  Once this branch is stabilized,
+the first version is tagged and released.  After this point, we accept
+only bug fixes in this branch.  Further point releases in this series
+are tagged on this branch, and all changes are merged back onto the
+//default// branch.
+When someone writes a patch for a bug, this should usually be
+committed to the latest active series branch which is affected by the
+bug.  Once a new series is released, we do not usually maintain the
+older series branches.  We may push bug fixes to these branches, but
+we are unlikely to create a new point release from it.
+===== Push access =====
+Push access to the official repositories is limited to developers
+employed or commisioned by UNINETT.
+====== Testing and Continuous Integration ======
+Much of NAV is **legacy code**, as defined by //Michael C. Feathers//:
+Code that has no tests.  We have been making an effort to introduce
+automated tests into the codebase the past couple of years, and hope
+to improve coverage in time.
+There are no tests for the legacy Java code, but many unit tests and
+integration tests now reside in the ''tests/'' subdirectory.
+===== Running tests =====
+We use ''[[http://pytest.org/|py.test]]'' to run the test suite.  A bundled version is
+included as ''runtests.py'' in the ''python/'' subdirectory, which is
+used to run the unit tests only when a ''make check'' command is
+issued in the ''python/'' subdirectory.
+Some of the test requirements aren't available on the Debian systems
+we use for development, so we often test inside a Python
+//virtualenv//.  A suitable virtualenv for testing (on Debian Lenny)
+can be created thus:
+<code bash>
+virtualenv .env
+. .env/bin/activate
+easy_install pip
+pip install -r tests/requirements.txt
+</code>
+There's also a script to create a test environment, complete with
+database initialization.  This is used by our CI server.  The
+following will configure and build NAV automatically, and install it
+into a directory called ''workspace/build''.  It will also create a
+suitable virtualenv in ''workspace/.env'', which you can activate
+before running tests:
+<code bash>
+export PGDATABASE=testdb
+export PGUSER=testuser
+tests/bootstrap-test-environment.sh workspace
+</code>
+===== Javascript testing =====
+Testing of javascript is in its infancy in NAV. We are currently using [[http://busterjs.org/|buster.js]] as testing toolkit.
+To install buster.js install [[http://nodejs.org/|node]] and then:
+<code>
+npm install -g buster
+</code>
+As we use [[http://requirejs.org/|require.js]] you need the AMD module of buster aswell. Install it in the /media/js directory:
+<code>
+npm install buster-amd
+</code>
+To run the tests you need to
+  - Start a buster server by typing ''buster-server''
+  - Capture browsers by pointing browsers to the buster-server (default localhost:1111)
+  - Go to /media/js
+  - Run the tests by typing ''buster-test''
+All tests are located under ''media/js/tests/''. Create new tests there. For syntax, assertions and related stuff take a look at the tests already there and [[http://busterjs.org/docs/|the buster docs]].
+===== Jenkins =====
+We use //Jenkins// (formerly //Hudson//) for Continuous Integration testing of
+NAV.  All the automated tests are run each time new changesets are pushed to
+the NAV repositories.  Jenkins also runs pylint to create stats on code
+quality.
+Our Jenkins installation is available on https://ci.nav.uninett.no/ .
-  import nav.db
+===== Tips and tricks =====
-  # Get a connection to the manage database
-  connection = nav.db.getConnection('default', 'manage')
-The above code will open a connection to the manage database, or, if
+===== Make fixtures for integration testing =====
-the connection had already been opened during the lifetime of the
-current process, returns the already existing connection from a
-connection cache.
-The 'default' parameter is there for legacy reasons; the db.conf file
+<code>
-allows one to configure separate database users for each subsystem
+from django.core import serializers
-(known as a script in db.conf) of NAV, but it is recommended to use
+from nav.models.manage import Netbox
-only one user for all NAV database connections - hence the default
-"subsystem".
+fixtures = serializers.serialize("xml", Netbox.objects.all()[:2])
+</code>
-Web interface
+Fixtures can so be used in your integration tests by extending
-=============
+the test case DjangoTransactionTestCase in nav.tests.cases
-When programming for NAV's web interface, a few special considerations
-need to be made.
-Mod_python
+See nav.tests.integration.l2trace_test for an example on applying
-----------
+fixtures for your particular test case.
-NAV uses mod_python to interface with the Apache web server.  See
-http://www.modpython.org/.
-Cheetah Templates
+Also keep in mind you have to make sure you have the model
------------------
+dependency in correct order when importing.
-The NAV web interface makes extensive use of Cheetah templates for
+Example: Netbox contains a location to a Room where it is located,
-generating its HTML output, see http://www.cheetahtemplate.org/ .
+you have to make sure Room's are imported first before importing
+Netbox's
-Most of the existing Cheetah templates are to be found in
+See https://docs.djangoproject.com/en/dev/topics/serialization/
-subsystem/webfront/nav/web/templates, although some of NAV's subsystems
-store their templates along with their code in their respective subsystem
-subdirectories. The compiled templates should be placed in the
-nav.web.templates package.
-If you are making a new web module for NAV, your module's Cheetah
+TODO: Be able to use [[https://docs.djangoproject.com/en/dev/ref/django-admin/#dumpdata-appname-appname-appname-model|django-admin's management command: dumpdata]]
-template should subclass MainTemplate.tmpl found in
+to create fixtures.
-subsystem/webfront/nav/web/templates/. See other templates for code
-examples of how to inherit from this template.
-Database connections in the web interface
------------------------------------------
-As stated above, use the nav.db.getConnection function to open or
-retrieve an existing database connection.  All NAV web modules share
-the same interpreter and namespace per Apache process, which also
-means that database connections will be shared between the modules
-running in each process.  Therefore, the following conventions apply
-for connections obtained from nav.db.getConnection:
-* Do not, under any circumstances, retain references to a database
-  connection between client requests.  Make sure to retrieve a new
-  connection at the start of each request cycle - the API will cache
-  connections between requests, and will automagically re-open broken
-  connections.  As the connection is shared between several modules,
-  retained references may be invalid in the next request cycle.
-* Do not explicitly close database connections.  Although the API will
+====== Submitting patches ======
-  try to reopen any closed or broken connections, you create extra
+Unless you are submitting one-off fixes for bugs and small issues,
-  overhead, and you don't play nice with the other web modules.
+please take the time to discuss your change proposals on the
+//nav-dev// mailing list.  This will increase the chances of having
+your patches accepted.
-* Do not enable/disable autocommit or alter a connection's transaction
+Base your patches on the relevant Mercurial branches.  If you are
-  isolation level, unless you make pretty darn sure to reset them to
+submitting a patch for an issue that affects the latest stable series,
-  their original states at the end of a request cycle.
+base your patch on that series branch.  If you are submitting patches
+containing new features, base them on the default branch.
-* NAV 3.0 makes connections autocommit by default, whereas NAV 3.1
+There are three common options for submitting patches:
-  will not - make sure to commit your transactions when needed.  NAV
-  will help unfortunate souls by attempting to commit transactions in
-  a mod_python cleanuphandler, but you should nevertheless explicitly
-  call connection.commit to avoid having your transactions
-  accidentally rolled back.
+  * The best way to submit your patches would be using Mercurial. Publish
+    your own Mercurial branch, and mail its URL to the //nav-dev// mailing
+    list.
+  * If unable to host a public Mercurial branch, export your changes
+    as a Mercurial bundle and attach it to an email addressed to the
+    //nav-dev// mailing list.
+  * If you have a single patch to submit, attach it to an email
+    addressed to the //nav-dev// mailing list.  Please **do not
+    patchbomb** the mailing list with multiple emails.

NAV Wiki

User Tools

Site Tools

Differences

Page Tools