OLD | NEW |
| 1 Pub is the package manager for Dart. |
| 2 |
1 # Contibuting to pub | 3 # Contibuting to pub |
2 | 4 |
3 Thanks for being interested in contributing to pub! Contributing to a new | 5 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 | 6 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 | 7 document is intended to get you up and running as quickly as possible. If you're |
6 looking for documentation on using pub, try | 8 looking for documentation on using pub, try |
7 [pub.dartlang.org](http://pub.dartlang.org/doc). | 9 [dartlang.org](https://www.dartlang.org/tools/pub/). |
8 | 10 |
9 The first step towards contributing is to contact the pub dev team and let us | 11 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 | 12 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 | 13 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. | 14 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. | 15 This will also let us give you specific advice about where to start. |
14 | 16 |
15 [misc@dartlang.org]: mailto:misc@dartlang.org | 17 [misc@dartlang.org]: mailto:misc@dartlang.org |
16 | 18 |
17 ## Organization | 19 ## Organization |
18 | 20 |
19 Pub isn't a package, but it's organized like one. It has four top-level | 21 Pub isn't a package, but it's organized like one. It has four top-level |
20 directories: | 22 directories: |
21 | 23 |
22 * `lib/` contains the implementation of pub. Currently, it's all in `lib/src/`, | 24 * `lib/` contains the implementation of pub. Currently, it's all in `lib/src/`, |
23 since there are no libraries intended for public consumption. | 25 since there are no libraries intended for public consumption. |
24 | 26 |
25 * `test/` contains the tests for pub. | 27 * `test/` contains the tests for pub. |
26 | 28 |
27 * `bin/` contains `pub.dart`, the entrypoint script that's run whenever a user | 29 * `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 | 30 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. | 31 run through shell scripts in `sdk/bin` at the root of the Dart repository. |
30 | 32 |
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 | 33 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 | 34 particular pub command. Each command is encapsulated in files in |
36 `lib/src/command/`. | 35 `lib/src/command/`. |
37 | 36 |
38 ## Running pub | 37 ## Running pub |
39 | 38 |
40 To run pub from the Dart repository, first [build Dart][building]. From the root | 39 To run pub from the Git repository, run: |
41 of the repo: | |
42 | 40 |
43 ./tools/build.py -m release | 41 dart bin/pub.dart |
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 | 42 |
51 ## Testing pub | 43 ## Testing pub |
52 | 44 |
53 Before any change is made to pub, all tests should pass. To run all the pub | 45 Before any change is made to pub, all tests should pass. To run a pub test, run: |
54 tests, run this from the root of the Dart repository: | |
55 | 46 |
56 ./tools/test.py -m release pub | 47 dart test/path/to/pub_test.dart |
| 48 |
| 49 A way to run all tests at once is coming soon. |
| 50 |
| 51 Some pub tests require specific versions of other packages. These packages are |
| 52 included in the repository as [Git submodules][]. To get them, run: |
| 53 |
| 54 [Git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules |
| 55 |
| 56 git submodule update --init |
57 | 57 |
58 Changes to pub should be accompanied by one or more tests that exercise the new | 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 | 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 | 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 | 61 [scheduled_test] package in its tests, so it's usually important to be familiar |
62 with that when adding tests. | 62 with that when adding tests. |
63 | 63 |
64 [scheduled_test]: http://pub.dartlang.org/packages/scheduled_test | 64 [scheduled_test]: http://pub.dartlang.org/packages/scheduled_test |
65 | 65 |
66 Pub tests come in two basic forms. The first, which is usually used to unit test | 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 | 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, | 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. | 69 `test/version_test.dart` contains unit tests for pub's Version class. |
70 | 70 |
71 The other form, used by most pub tests, is usually used for integration tests of | 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 | 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 | 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, | 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 | 75 `tests/get/hosted/get_transitive_test.dart` tests the resolution of transitive |
76 hosted dependencies when using `pub get`. | 76 hosted dependencies when using `pub get`. |
77 | 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 | 78 ## Landing your patch |
85 | 79 |
86 All patches to the Dart repo, including to pub, need to undergo code review | 80 All patches to official Dart packages, including to pub, need to undergo code |
87 before they're submitted. The full process for putting up your patch for review | 81 review before they're submitted. The full process for putting up your patch for |
88 is [documented elsewhere][contributing]. | 82 review is [documented elsewhere][contributing]. |
89 | 83 |
90 [contributing]: https://code.google.com/p/dart/wiki/Contributing | 84 [contributing]: https://github.com/dart-lang/sdk/wiki/Contributing |
OLD | NEW |