1 # Adding a directory to catapult 2 3 ## Where should the code live? 4 5 Catapult is intended to be a set of performance tools, mostly based on tracing, 6 for developers of Chromium and other software to analyze that softwares 7 performance. It has a lot of supporting libraries and tooling to make this 8 happen. Wed like to create an organizational structure that makes it easy to 9 find the performance tooling developers want, and hard to accidentally depend 10 on something internal. Furthermore, wed like to make it easy for code in 11 catapult to eventually grow to its own repo, when possible. To that end, we 12 use these guidelines to decide where code should live. 13 14 * Is it a **performance product**? Meant be used by external developers for 15 performance analysis? Some examples include telemetry, perf dashboard. If 16 so, it should be at `toplevel`. 17 * Is it used only by our buildbot or build process? Put it in 18 `catapult_build`. 19 * If it's neither of the above, it should go in `common/` 20 * If it is aspiring to be its own repo someday, that doesn't affect where it 21 goes. You should follow the above rules for directory placement. Third 22 party must only be real third party repos to conform to rules of repos 23 which include catapult. 24 * If something is experimental, then talk with the catapult admins to build 25 the best guess of where it should go. 26 27 ## How should directories be structured? 28 We have some rules on directory structure to add consistency and avoid 29 overloaded python imports. 30 31 * Toplevel directories are **not** modules. E.g. if `x` is a toplevel 32 directory, `x/__init__.py` **does not** exist. Directories in `common/` 33 do not have this restriction. 34 * Toplevel directories and directories in `common` should centralize all 35 their path computation and sys.path manipulation in their master init file 36 ([example](https://github.com/catapult-project/catapult/blob/master/telemetry/telemetry/__init__.py)). 37 * Projects using web server should provide a module which defines all the 38 search paths to their html & javascript resources in their top directory 39 ([example](https://github.com/catapult-project/catapult/blob/master/dashboard/dashboard_project.py)). 40 * Build code should be separate from production code. Build scripts for 41 projects should be in `x/x_build/` 42 * If you have a feature that has an implementation in JS and Py, then it 43 should be in the same folder. 44 * HTML search paths are arranged such that they have the same _name_ as they 45 would in python. E.g. `tracing/tracing/base/math.html` is 46 `/tracing/base/math.html` for an HTML import, and 47 `tracing/tracing/base/math.py` is `tracing.base.math` in python. 48 * Executable files (e.g. files chmodded to +x) must live in `x/bin`. 49 `bin/` must not be a module, e.g. contain `__init__.py`, as such a name 50 would create namespace conflicts. Executable files should **not** have a 51 `.py` extension. 52 * We use a single dev server, `$catapult/bin/run_dev_server`; and have 53 per-project `bin/run_dev_server_tests` scripts. 54 * All python modules should have unique names. `$catpult/catapult_build` 55 instead of `$catapult/build`. 56
