@galaxyproject/galaxy-client 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# Client Build System
+
+Installs, stages, and builds the client-side scripts necessary for running the
+Galaxy webapp. When started through `run.sh` or any other method that utilizes
+`scripts/common_startup.sh`, Galaxy will (since 18.09) _automatically_ build
+the client as a part of server startup, when it detects changes, unless that
+functionality is explicitly disabled.
+
+The base dependencies used are Node.js and Yarn. Galaxy now includes these in
+the virtual environment, and they can be accessed by activating that with `.
+.venv/bin/activate` from the Galaxy root directory.
+
+If you'd like to install your own dependencies, on OSX the easiest way to get
+set up is using `homebrew` and the command `brew install nodejs yarn`. More
+information, including instructions for other platforms, is available at
+[https://nodejs.org](https://nodejs.org) and
+[https://yarnpkg.com/](https://yarnpkg.com).
+
+The Galaxy client build has necessarily grown more complex in the past several
+years, but we are still trying to keep things as simple as possible for
+everyone. If you're having any trouble with building the client after following
+the instructions below, please create an issue on GitHub or reach out for help
+directly on Gitter at
+[https://gitter.im/galaxyproject/Lobby](https://gitter.im/galaxyproject/Lobby).
+
+## Complete Client Build
+
+There are many moving parts to the client build system, but the entry point for
+most people is the 'client' rule in the Makefile at the root of the Galaxy
+repository. Execute the following to perform a complete build suitable for
+local development, including dependency staging, style building, script
+processing, and bundling. This is a development-specific build which includes
+extra debugging features, and excludes several production optimizations made
+during the build process.
+
+    make client
+
+For a production build, suitable for deploying to a live server, use the
+following:
+
+    make client-production
+
+And, lastly, if you want a production build that includes sourcemaps to allow
+for inspection of live javascript to facilitate debugging, use:
+
+    make client-production-maps
+
+Important Note: The Galaxy repository does not include client script artifacts,
+and these should not be committed.
+
+## Automatic Rebuilding
+
+When you're actively developing, it is convenient to have the client
+automatically rebuild every time you save a file. You can do this using:
+
+    make client-watch
+
+This will first stage client dependencies, initiate a build, and then will
+watch for changes in any of the galaxy client source files.  When a file is
+changed, the client will automatically rebuild, after which you can refresh
+your browser to see changes.
+
+For even more rapid development you can use the webpack development server,
+which takes advantage of hot module replacement (HMR). This technique allows
+swapping out of javascript modules while the application is running without
+requiring a full page reload most of the time, at least in the more modern
+parts of the application.
+
+The command below starts a special webpack dev server after a client
+build.
+
+    make client-dev-server
+
+This will start up an extra client development server running on port 8081.
+Open your browser to http://localhost:8081 (instead of the default 8080 that
+Galaxy would run on), and you should see Galaxy like normal.  Except now, when
+you change client code it'll automatically rebuild *and* reload the relevant
+portion of the application for you. Lastly, if you
+are running Galaxy at a location other than the default, you can specify a
+different proxy target (in this example, port 8000) using the GALAXY_URL
+environment variable:
+
+    GALAXY_URL="http://localhost:8000" make client-dev-server
+
+Sometimes you want to run your local UI against a remote Galaxy server. This is also possible, if you enable `CHANGE_ORIGIN` flag 
+
+    CHANGE_ORIGIN=true GALAXY_URL="https://usegalaxy.org/" make client-dev-server
+
+## Running a Separate Server
+
+When developing the client it can be helpful to run a local server for the
+client to connect to, and run the client separately with one of the above
+commands. This command will run galaxy without building the client:
+
+    make skip-client
+
+## Changing Styles/CSS
+
+Galaxy uses Sass for its styling, which is a superset of CSS that compiles down
+to regular CSS. Most Galaxy styling source (.scss) files are kept in
+`client/src/style/scss`. There are additionally style blocks alongside some Vue
+components -- styles that are particular to that individual component and do
+not apply site-wide.
+
+On build, the compiled css bundle is served at `/static/style/base.css`.
+
+As mentioned above, `make client` will rebuild styles, as a part of the webpack
+build. For iterative development, "Watch Mode" rebuilds as described above do
+include style changes.
+
+## Client-Side Unit Testing
+
+Galaxy's client is undergoing an extensive refactoring and modernizing process.
+As part of this initiative, we would like to request that all new client-side
+code submissions come with accompanying javascript unit-tests for the
+developer-facing API of your new code.
+
+### Testing Technologies
+
+[Galaxy uses Jest](https://jestjs.io/) for its client-side unit testing
+framework.
+
+For testing Vue components, we use the [Vue testing
+utils](https://vue-test-utils.vuejs.org/) to mount individual components in a
+test bed and check them for rendered features.  Please use jest-based mocking
+for isolating test functionality.
+
+A set of older qUnit tests also exist which will be phased-out as the code they
+support is replaced with modern component-based implementations. In the
+meantime, we still run the qunit tests in sequence.
+
+### Running the tests
+
+#### At Build-Time
+
+To simply run all the javascript unit tests, you can use make from the root
+directory. This is what happens during a complete client build.
+
+     make client-test
+
+#### During Development
+
+During client-side development, it is more convenient to have granular testing
+options. The various testing scripts are defined inside package.json within the
+client folder, and are called with `yarn` as demonstrated in the
+following commands.
+
+This is what CI is going to run, and also what 'make client-test' invokes,
+executing all the client tests:
+
+     yarn run test
+
+You can also bypass qunit and single-run all of the jest tests like so:
+
+     yarn run jest
+
+Or, if you really want to run just the qunit tests:
+
+    yarn run qunit
+
+##### Watch and rerun jest unit tests every time a source file changes
+
+This is incredibly handy, and there are a host of options in the interactive
+terminal this starts for executing Jest tests.
+
+     yarn run jest-watch
+
+##### Run only specified test files when a source file changes
+
+    yarn run jest-watch MyModule
+
+    yarn run jest-watch Dialog
+
+    yarn run jest-watch workflow/run