From becf05d4a6b40501f9982c737df555c81c3df1ab Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Fri, 31 Oct 2014 11:14:31 -0700 Subject: [PATCH] [Structure] Add top-level README Add top level README file describing, in broad terms, the structure of the project. In particular, this documents the naming conventions which support build and test, and provides a short summary of how these both run. WTD-519. --- README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000000..58ccb23e31 --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +# Open MCT Web + +Open MCT Web is a web-based platform for mission operations user interface +software. + +## Bundles + +A bundle is a group of software components (including source code, declared +as AMD modules, as well as resources such as images and HTML templates) +that are intended to be added or removed as a single unit. A plug-in for +Open MCT Web will be expressed as a bundle; platform components are also +expressed as bundles. + +A bundle is also just a directory which contains a file `bundle.json`, +which declares its contents. + +The file `bundles.json` (note the plural), at the top level of the +repository, is a JSON file containing an array of all bundles (expressed as +directory names) to include in a running instance of Open MCT Web. Adding or +removing paths from this list will add or remove bundles from the running +application. + +### Bundle Contents + +A bundle directory will contain: + +* `bundle.json`, the declaration of the bundles contents. +* A source code directory, named `src` by convention. This contains all + JavaScript sources exposed by the bundle. These are declared as + AMD modules. +* A directory for other resources, named `res` by convention. This + contains all HTML templates, CSS files, images, and so forth to be + used within a given bundle. +* A library directory, named `lib` by convention. This contains all + external libraries used and/or exposed by the bundle. +* A test directory, named `test` by convention. This contains all unit + tests declared for the bundle, as well as a `suite.json` that acts + as a listing of these dependencies. See the section on unit testing + below. + +Following these bundle conventions is required, at present, to ensure +that Open MCT Web (and its build and tests) execute correctly. + +## Tests + +The repository for Open MCT Web includes a test suite that can be run +directly from the web browser, `test.html`. This page will: + +* Load `bundles.json` to determine which bundles are in the application. +* Load `test/suite.json` to determine which source files are to be tested. + This should contain an array of strings, where each is the name of an + AMD module in the bundle's source directory. For each source file: + * Code coverage instrumentation will be added, via Blanket. + * The associated test file will be loaded, via RequireJS. These will + be located in the bundle's test folder; the test runner will presume + these follow a naming convention where each module to be tested has a + corresponding test module with the suffix `Spec` in that folder. +* Jasmine will then be invoked to run all tests defined in the loaded + test modules. Code coverage reporting will be displayed at the bottom + of the test page. + +At present, the test runner presumes that bundle conventions are followed +as above; that is, sources are contained in `src`, and tests are contained +in `test`. Additionally, individual test files must use the `Spec` suffix +as described above. + +An example of this is expressed in `platform/framework`, which follows +bundle conventions. + +## Build + +Open MCT Web includes a Maven command line build. Although Open MCT Web +can be run as-is using the repository contents (that is, by viewing +`index.html` in a web browser), and its tests can be run in-place +similarly (that is, by viewing `test.html` in a browser), the command +line build allows machine-driven verification and packaging. + +This build will: + +* Check all sources (excluding those in directories named `lib`) with + JSLint for code style compliance. The build will fail if any sources + do not satisfy JSLint. +* Run unit tests. This is done by running `test.html` in a PhantomJS + browser-like environment. The build will fail if any tests fail. +* Package the application as a `war` (web archive) file. This is + convenient for deployment on Tomcat or similar. This archive will + include sources, resources, and libraries for bundles, as well + as the top-level files used to initiate running of the application + (`index.html` and `bundles.json`). + +Run as `mvn clean install`.