OLD | NEW |
| (Empty) |
1 # Contributing to pub | |
2 | |
3 Thanks for being interested in contributing to pub! Contributing to a new | |
4 project can be hard: there's a lot of new code and practices to learn. This | |
5 document is intended to get you up and running as quickly as possible. If you're | |
6 looking for documentation on using pub, try | |
7 [pub.dartlang.org](http://pub.dartlang.org/doc). | |
8 | |
9 The first step towards contributing is to contact the pub dev team and let us | |
10 know what you're working on, so we can be sure not to start working on the same | |
11 thing at the same time. Just send an email to [misc@dartlang.org] letting us | |
12 know that you're interested in contributing and what you plan on working on. | |
13 This will also let us give you specific advice about where to start. | |
14 | |
15 [misc@dartlang.org]: mailto:misc@dartlang.org | |
16 | |
17 ## Organization | |
18 | |
19 Pub isn't a package, but it's organized like one. It has four top-level | |
20 directories: | |
21 | |
22 * `lib/` contains the implementation of pub. Currently, it's all in `lib/src/`, | |
23 since there are no libraries intended for public consumption. | |
24 | |
25 * `test/` contains the tests for pub. | |
26 | |
27 * `bin/` contains `pub.dart`, the entrypoint script that's run whenever a user | |
28 types "pub" on the command line or runs it in the Dart editor. This is usually | |
29 run through shell scripts in `sdk/bin` at the root of the Dart repository. | |
30 | |
31 * `resource/` contains static resource files that pub uses. They're | |
32 automatically distributed in the Dart SDK. | |
33 | |
34 It's probably easiest to start diving into the codebase by looking at a | |
35 particular pub command. Each command is encapsulated in files in | |
36 `lib/src/command/`. | |
37 | |
38 ## Running pub | |
39 | |
40 To run pub from the Dart repository, first [build Dart][building]. From the root | |
41 of the repo: | |
42 | |
43 ./tools/build.py -m release | |
44 | |
45 You'll need to re-build whenever you sync the repository, but not when you | |
46 modify pub or any packages it depends on. To run pub, just run `sdk/bin/pub` (or | |
47 `sdk/bin/pub.bat` on Windows). | |
48 | |
49 [building]: https://code.google.com/p/dart/wiki/Building | |
50 | |
51 ## Testing pub | |
52 | |
53 Before any change is made to pub, all tests should pass. To run all the pub | |
54 tests, run this from the root of the Dart repository: | |
55 | |
56 ./tools/test.py -m release pub | |
57 | |
58 Changes to pub should be accompanied by one or more tests that exercise the new | |
59 functionality. When adding a test, the best strategy is to find a similar test | |
60 in `test/` and follow the same patterns. Note that pub makes wide use of the | |
61 [scheduled_test] package in its tests, so it's usually important to be familiar | |
62 with that when adding tests. | |
63 | |
64 [scheduled_test]: http://pub.dartlang.org/packages/scheduled_test | |
65 | |
66 Pub tests come in two basic forms. The first, which is usually used to unit test | |
67 classes and libraries internal to pub, has many tests in a single file. This is | |
68 used when each test will take a short time to run. For example, | |
69 `test/version_test.dart` contains unit tests for pub's Version class. | |
70 | |
71 The other form, used by most pub tests, is usually used for integration tests of | |
72 user-visible pub commands. Each test has a file to itself, which is named after | |
73 the test description. This is used when tests can take a long time to run to | |
74 avoid having the tests time out when running on the build bots. For example, | |
75 `tests/get/hosted/get_transitive_test.dart` tests the resolution of transitive | |
76 hosted dependencies when using `pub get`. | |
77 | |
78 When testing new functionality, it's often useful to run a single test rather | |
79 than the entire test suite. You can do this by appending the path to the test | |
80 file to the test command. For example, to run `get/relative_symlink_test.dart`: | |
81 | |
82 ./tools/test.py -m release pub/get/relative_symlink_test | |
83 | |
84 ## Landing your patch | |
85 | |
86 All patches to the Dart repo, including to pub, need to undergo code review | |
87 before they're submitted. The full process for putting up your patch for review | |
88 is [documented elsewhere][contributing]. | |
89 | |
90 [contributing]: https://code.google.com/p/dart/wiki/Contributing | |
OLD | NEW |