| OLD | NEW |
| (Empty) |
| 1 # Sugar | |
| 2 | |
| 3 [](http://t
ravis-ci.org/andrewplummer/Sugar) | |
| 4 | |
| 5 A Javascript library for working with native objects. | |
| 6 http://sugarjs.com/ | |
| 7 | |
| 8 | |
| 9 ## Upgrading | |
| 10 | |
| 11 If you are upgrading from an older version, please have a look at [`CAUTION.md`]
(https://github.com/andrewplummer/Sugar/blob/master/CAUTION.md) which is a vette
d changelog | |
| 12 that details the severity of what has changed, and (sometimes) strategies for mi
grating. | |
| 13 Going through this before you upgrade can make the process a lot less painful! | |
| 14 Also please refer there for notes about a patch that applies to versions prior t
o v1.3.9. | |
| 15 | |
| 16 | |
| 17 ## Edge Build | |
| 18 | |
| 19 Public stable releases will be made available on the site and also exist in `rel
ease/`. | |
| 20 Any push made to `master` branch *should* have its unit tests passing, although
maybe not | |
| 21 in all browsing environments (IE, etc) to ensure that it is stable, at least to
a certain degree. | |
| 22 | |
| 23 | |
| 24 ## Custom Builds | |
| 25 | |
| 26 Sugar now allows custom builds that let you opt in or out packages. This can be
done [here](http://sugarjs.com/customize). | |
| 27 Custom builds can also be created with `script/build_custom.rb`. With ruby insta
lled, simply call: | |
| 28 | |
| 29 ``` | |
| 30 ruby script/build_custom.rb core array string | |
| 31 ``` | |
| 32 | |
| 33 listing the packages you want to include. The advantage of using this | |
| 34 script is that it will perform all the minification on the fly, providing more f
ine-grained control by allowing you to | |
| 35 manipulate the source code in `lib/` before building. If you want to remove spec
ific methods from a package, you can do it this way. | |
| 36 Be careful about removing dependencies, however, especially methods in `core.js`
, the extending methods of which are required. | |
| 37 | |
| 38 | |
| 39 ## Unit Tests Node | |
| 40 | |
| 41 Use the `npm test` command to run unit tests. | |
| 42 | |
| 43 | |
| 44 ## Date Localizations | |
| 45 | |
| 46 Sugar has the following localizations available: | |
| 47 | |
| 48 - English (en) | |
| 49 - French (fr) | |
| 50 - German (de) | |
| 51 - Spanish (es) | |
| 52 - Italian (it) | |
| 53 - Russian (ru) | |
| 54 - Finnish (fi) | |
| 55 - Swedish (sv) | |
| 56 - Danish (da) | |
| 57 - Dutch (nl) | |
| 58 - Polish (pl) | |
| 59 - Portuguese (pt) | |
| 60 - Korean (ko) | |
| 61 - Japanese (ja) | |
| 62 - Simplified Chinese (zh-CN) | |
| 63 - Traditional Chinese (zh-TW) | |
| 64 | |
| 65 | |
| 66 These files can be added separately or built into the main package on the [custo
mize page](http://sugarjs.com/customize). | |
| 67 In addition to these major locales, custom locales can be added using: | |
| 68 | |
| 69 ``` | |
| 70 Date.addLocale(LOCALE_CODE, LOCALIZATION_OBJECT) | |
| 71 ``` | |
| 72 | |
| 73 Documentation for this available [here](http://sugarjs.com/dates). Also refer to
`lib/locales` for examples of what kind of data and formats are required in loc
alization objects. All localizations, including those not found in the main pack
age will be kept here. | |
| 74 | |
| 75 | |
| 76 | |
| 77 ## Timezones | |
| 78 | |
| 79 Dealing with timezones in Javascript can be tricky. Although timezones are outsi
de the scope of Sugar, it does provide a hook that can allow timezone shifted da
tes to be used internally in place of normal ones. See [the date reference](http
://sugarjs.com/dates#timezones) for more. | |
| 80 | |
| 81 | |
| 82 ## Contributing Locales | |
| 83 | |
| 84 If you do add a custom format for your locale, please consider forking and addin
g it to the repo! This especially includes the addition of new locales, but also
new formats or tweaks to existing locales. Not everything can be added to the m
ain package, but I would like to have as many languages/formats as possible avai
lable. When adding a locale contribution, the most important thing is to add uni
t tests that assert the correct format. These unit tests are found at `test/envi
ronments/sugar/date_LOCALE.js`. Simply add or adjust the formats for the locale
(the more tests, the better!) and issue me a pull request -- I will update the c
ode to add these locales/formats. Have a look at other unit tests files for an e
xample of the unit testing format. | |
| 85 | |
| 86 | |
| 87 ## Contributing Lib Comparisons | |
| 88 | |
| 89 Lib comparisons to various other libraries can be seen at http://sugarjs.com/lib
s. This is one of the areas where contributions are most welcome, as I don't hav
e extensive knowledge of many different libraries, and there is much to cover. T
o contribute simply find or create the appropriate lib name in `docs/libs`, and
follow the format provided. This will be an ongoing process, and I will push cha
nges here out to the site every so often. | |
| 90 | |
| 91 | |
| 92 ## Other Contributions | |
| 93 | |
| 94 For other contributions, please add well formed unit tests in the Sugar environm
ent at `test/environments/sugar/MODULE.js`. Unit tests can be run directly in th
e browser from `test/default.html`, and should all be passing in all major brows
ers (Webkit,Mozilla,Opera, and IE6+). Node.js unit tests should also be passing
and can be run in the console with `npm test`. | |
| 95 | |
| 96 Also note that the source code is in the `lib` directory, and `release` is autom
atically built, so there is no need to changes files there. | |
| 97 | |
| OLD | NEW |