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 |