searchux-delve v1.0.0

Search User Experience (SearchUX)

This Visual Studio Team Services (VSTS/VSO) Git repository holds the Search User Experience (SearchUX) source code.

Prerequisites

1. Install the latest release of nvm: https://github.com/coreybutler/nvm-windows/releases This is used to install the different verions of node.js which again is used to install modules that we use to build stuff.

• Do nvm install [version] to install a version of node.js.

2. Install Git: http://www.git-scm.com/download -- This is used to sync bits and check in and such. During install, choose "Use Git from the Windows Command Prompt". On the line ending options screen, choose "Checkout as-is, commit as-is".
3. Install the Git Credential Manager.
4. Set the environment variable VSCODE_TSJS to "1". This is to make VS Code understand Typescript 1.8 syntax.
5. Configure your machine to get NPM packages from the internal Microsoft package repo.

Initial Clone

1. Make a root folder for your repositories (example: C:\git) and go there

2. Open cmd and run:

git clone https://msfast.visualstudio.com/DefaultCollection/FAST/_git/searchux .

3. Log in to VSTS when the credential window appears.

Development

Once cloned, go to your project's root folder and run the following steps

1. npm install -g webpack jasmine typescript (This installs the webpack module bundler, the Jasmine test framework, and the typescript compiler.)

2. npm install to install the rest of the required npm packages

3. To edit the code, open a directory in VS Code. If you want to have everything in the editor, use code . to open the root path, or use code packages to see all packages but nothing else. If you want to work on just one package, you can open for example code packages/searchux.

4. Build:

   4.1 To build the demo applications run npm start

   4.2 To build the searchux-sphome package, go to packages/searchux-sphome and run webpack

   4.3 To build the searchux-delve package, go to packages/searchux-delve and run webpack

Use webpack -w if you want webpack to recompile automatically as you edit the code.

Branching structure

We are using the Git Flow branching strategy. The develop branch is the stable branch for the latest version. Features may be developed by branching off from develop and merging back into it when done. Feature branches can be named anything, but if you name them with the f/ prefix, builds will be triggered by every push, so this naming convention is recommended. Releases are made by creating a release branch that branches off develop and merges into master. Or, alternatively, merging directly from develop to master. Either way, all merges to master should be squashed, using git merge --squash, to keep the history on the master branch nice and clean.

Builds, versioning, and releases

Whenever you push to a feature branch starting with the f/ prefix, or to develop, a new development build is triggered in VSTS. The development build verifies that all packages build correctly (TODO: and that all unit tests pass), but does not release any new versions of the packages.

Whenever you push to the master branch, a new release build is triggered, with a new unique version number. Remember to check that the change log in CHANGELOG.md is properly updated before pushing. Version numbers are on the form major.minor.patch. A new build will just bump the patch version number, which is appropriate for bug fixes only. If you add a backwards-compatible feature, you should bump the minor version number. If you make a backwards-incompatible change, you should bump the major version number. The release version numbers are bumped by editing the appropriate variables in the VSTS build definition.

Using npm link to test changes during development

TODO. Describe this technique.

Setting up automatic copying of files into Delve, SharePoint Home and Team Sites repositories

If you create a file named local.config.js in the packages/searchux-sphome directory and in the packages/searchux-delve directory like so:

module.exports = {
    osloRoot: "c:\\path\\to\\oslo\\git\\repo",
    sphomeroot: "c:\\path\\to\\sphome-next\\git\\repo",
    spclientroot: "c:\\path\\to\\sp-client\\git\\repo"
};

You will automatically copy the javascript bundles and d.ts files into the host app repositories, overwriting the installed packages there, whenever you run webpack. This can be handy when you're doing parallel development in both SearchUX and one or more of the host apps.

Unit testing

Unit tests are written using the jasmine framework and the tests for a module foo.ts live in a file named foo.tests.ts, in the same folder. All tests are explicitly imported in the tests.ts module. If you forget to import them there, your tests won't run.

To compile and run the unit tests, do the following: 1. Go to the root folder and type npm run compile-tests. This starts the typescript compiler in watch mode, and compiles everything referenced from tests.ts. 2. Open the file testrunner.html in a browser. This page will execute the tests and display the results. Whenever you want to re-run the tests, just refresh the page in your browser. 3. You may on occasion need to edit testrunner.js to configure how modules are resolved when compiling unit tests. In particular, if you add a new external dependency, or if you add a CSS/less file that should be ignored when testing, you will need to edit this file.

Alternatively, use karma to run your tests: 1. Go to the root folder and type npm test. This will automatically run all tests defined in any of the **/*.tests.ts files in your tree.

Documentation build

TODO: Fix the documentation build and describe it here. Documentation will be deployed to http://searchux/

More information

• CSS in Search User Experience (SearchUX) repository