1Babel Development 2================= 3 4Babel as a library has a long history that goes back to the Trac project. 5Since then it has evolved into an independently developed project that 6implements data access for the CLDR project. 7 8This document tries to explain as best as possible the general rules of 9the project in case you want to help out developing. 10 11Tracking the CLDR 12----------------- 13 14Generally the goal of the project is to work as closely as possible with 15the CLDR data. This has in the past caused some frustrating problems 16because the data is entirely out of our hand. To minimize the frustration 17we generally deal with CLDR updates the following way: 18 19* bump the CLDR data only with a major release of Babel. 20* never perform custom bugfixes on the CLDR data. 21* never work around CLDR bugs within Babel. If you find a problem in 22 the data, report it upstream. 23* adjust the parsing of the data as soon as possible, otherwise this 24 will spiral out of control later. This is especially the case for 25 bigger updates that change pluralization and more. 26* try not to test against specific CLDR data that is likely to change. 27 28Python Versions 29--------------- 30 31At the moment the following Python versions should be supported: 32 33* Python 2.7 34* Python 3.4 and up 35* PyPy tracking 2.7 and 3.2 and up 36 37While PyPy does not currently support 3.3, it does support traditional 38unicode literals which simplifies the entire situation tremendously. 39 40Documentation must build on Python 2, Python 3 support for the 41documentation is an optional goal. Code examples in the docs preferably 42are written in a style that makes them work on both 2.x and 3.x with 43preference to the former. 44 45Unicode 46------- 47 48Unicode is a big deal in Babel. Here is how the rules are set up: 49 50* internally everything is unicode that makes sense to have as unicode. 51 The exception to this rule are things which on Python 2 traditionally 52 have been bytes. For example file names on Python 2 should be treated 53 as bytes wherever possible. 54* Encode / decode at boundaries explicitly. Never assume an encoding in 55 a way it cannot be overridden. utf-8 should be generally considered 56 the default encoding. 57* Dot not use ``unicode_literals``, instead use the ``u''`` string 58 syntax. The reason for this is that the former introduces countless 59 of unicode problems by accidentally upgrading strings to unicode which 60 should not be. (docstrings for instance). 61 62Dates and Timezones 63------------------- 64 65Generally all timezone support in Babel is based on pytz which it just 66depends on. Babel should assume that timezone objects are pytz based 67because those are the only ones with an API that actually work correctly 68(due to the API problems with non UTC based timezones). 69 70Assumptions to make: 71 72* use UTC where possible. 73* be super careful with local time. Do not use local time without 74 knowing the exact timezone. 75* `time` without date is a very useless construct. Do not try to 76 support timezones for it. If you do, assume that the current local 77 date is assumed and not utc date. 78