diff --git a/README.md b/README.md index 53f25b1..c80c452 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,36 @@ # Web Perf Toolbar -A drop-in toolbar to visualize web client performance. +A component to visualize client performance on your site for the current page. -## Engineering Spec and Work Tracking -The initial work is being completed by Sway engineers. +Shipped as a single JavaScript file with no runtime dependencies, this toolbar drops into your existing sites with a single script tag and barely any configuration. Designed to be injected into a page for developers or stakeholders -The [initial engineering spec](https://microsoft.sharepoint.com/:w:/r/teams/Sway/_layouts/15/Doc.aspx?sourcedoc=%7Bb321f8b7-6492-4031-99bf-70c3f5080501%7D&action=edit) is access-limited to Microsoft employees. +## Road Map -Work tracking is within the Sway project in Office's Visual Studio, under [Task Group 2031043](https://office.visualstudio.com/Sway/_workitems/edit/2031043). - -Once the core version of this tool ships, documentation will need to be updated and the initial spec will be abandoned in favor of describing, tracking, and planning work in this repository. +Note: This project follows semver and is pre-release. Until a 1.0 release, the public API may change. ## Getting Started -1. `npm install` +1. [Visual Studio Code](https://code.visualstudio.com/) is the recommended editor. We [have configured](./.vscode/extensions.json) recommended extensions for working with this project. +2. Install the npm dev dependencies. `npm install` +3. Run the demo: `npm run demo` -## Commands +## Commands (`npm run ...`) -- `npm run build` Kicks off a Webpack build. -- `npm run test` Builds then launches a test runner in IE and Chrome that watches for changes. -- `npm run demo` Builds then launches a page with a demo of the toolbar. +### Main Commands +- `demo` Builds then launches a page with a demo of the toolbar. +- `build` Kicks off a Webpack production build. +- `test` Builds then launches a test runner in IE and Chrome that watches for changes. +- `check` Compiles, lints, and tests everything. **This command must be run and the output must be clean before checking in.** + +### Source Commands +- `tslint` Run tslint on the toolbar sources. +- `tsc` Compile the toolbar TypeScript sources directly (no Webpack). +- `tsc-verbose` Same as above, but verbose compiler. + +### Test commands +- `test-once` Builds then launches a single test run. +- `test-tslint` Runs tslint on the test sources. +- `test-tsc` Compiles the test TypeScript sources directly (no Webpack/Karma). +- `test-tsc-verbose` Same as above, but verbose compiler. ## Contributing @@ -33,3 +45,42 @@ provided by the bot. You will only need to do this once across all repos using o This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +To get started, see [Adding To The Toolbar](./docs/adding-to-the-toolbar.md). + +## Maintainers +- @AdamTReineke (Admin, primary contact) +- @JoshuaKGoldberg (Admin) +- Dadstart (Admin) + +## Releasing +This project follows the [semver](https://semver.org/) versioning convention of major.minor.patch. + +- Changing the [public API](./src/toolbar.ts) will bump the **major** version. +- Adding a whole new panel, changing/removing a panel configuration, or adding significant panel features will bump the **minor** version. +- Bug fixes or minor tweak to a panel, including adding new optional panel configurations, will bump the **patch** version. + +0. Figure out what the new version number will be. +0. If leaving `0.1.0-alpha`, update the Security notice below and remove this line. +1. From `develop` branch, create a new branch for the release: `git checkout -b release-vxx.xx.xx` +2. `npm run check` should be clean. +3. Verify the [demo](./index.html) was updated to show any new panels. +4. `npm run demo` should show the different panels in the toolbar. +5. Bump the version in [package.json](./package.json). +6. Update the road map in this file to address completed work. +7. Make then merge a pull request from the new branch to `master`. +8. Tag with the new version number. `git tag vxx.xx.xx; git push --tags` +9. Push to NPM. *TODO: What are the steps?* + +There is not a regular release schedule. + +## Reporting Security Issues + +**DURING ALPHA ONLY**: Open a new issue so we can address the issue before leaving alpha. Once this project leaves alpha, the default Microsoft Security message below should be unstruck and followed. + +~~Security issues and bugs should be reported privately, via email, to the Microsoft Security +Response Center (MSRC) at [secure@microsoft.com](mailto:secure@microsoft.com). You should +receive a response within 24 hours. If for some reason you do not, please follow up via +email to ensure we received your original message. Further information, including the +[MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in +the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).~~ diff --git a/docs/adding-to-the-toolbar.md b/docs/adding-to-the-toolbar.md new file mode 100644 index 0000000..cadea75 --- /dev/null +++ b/docs/adding-to-the-toolbar.md @@ -0,0 +1,62 @@ +# Adding To The Toolbar + +## Be Familiar With The Tech Stack + +- Language: TypeScript +- Test Runner: Karma +- Assertion Library: Mocha +- Linter: tslint +- Packaging: Webpack + +## Follow The Implicit Coding Guidelines + +- The coding style should be pretty standard and enforced with tslint. +- Using VSCode with the recommended extensions exposes tslint violations at dev time so you aren't surprised when you build. +- Don't violate tslint rules without having a good reason and justify disabling rules for a line or block with a comment when you do. +- There is a high bar for disabling tslint rules globally through tslint.json. + +TODO: Some rules are annoying formatting ones. We need to set up prettier and/or auto-fixing on save for tslint. + +## Understand The Architecture + +### Toolbar + +- A `Toolbar` is constructed with a list of `IPanel` constructors and `IPanelConfig` configurations. + +### Panels + +- Panels extend from `IPanel`. +- Panels provide a list of `Button` objects displayed by the toolbar. +- Panels are rendered in a `PanelFrame` provided by the `Toolbar`. +- These panels are constructed with a configuration object that extends `IPanelConfig`. +- There should be a default configuration object with values for every configuration property. These default values should be used when +- (Recommended) UI strings should be available in a panel's configuration so they can be overridden. + +### Buttons + +- Buttons are so basic their design is quite opinionated. +- Buttons have a simple visual: icon, text, and background color. +- Buttons toggle the display of the `PanelFrame` when they are clicked. +- Buttons are constructed with a configuration object that extends `IButtonConfiguration`. + +## Create A New Panel + +1. Create an interface for the panel configuration. Start simple, maybe just a string for the panel name. +2. Create a default configuration object. +3. Create the class for your panel. + 1. You probably want to duplicate the constructor from an existing panel. + 2. Determine what you want your button to show. Maybe just a smiley face and a random number at first. + 3. Determine what you want the panel to show. Start by setting the innerHTML of the DOM object that is passed in to the render function to something like the title you have in the config object. +4. Update `./src/index.ts` to include a reference to your panel. (Since we're a library and your panel isn't referenced, it won't be output since it isn't reachable. I wonder if this could be fixed with a config change, if it can, please send a PR.) +5. Update the Toolbar constructor configuration in `./index.html` to include references to your new panel and configuration. +6. Run the demo and see your toolbar! `npm run demo` + +### What now? Share it! + +If you are ready to share your panel with the world, add some tests then send a PR! + +### Can't share? + +If you have to keep your new panel private, don't worry. You don't have to maintain your own fork of this repository. As long as you have implemented the interfaces and your panel is loaded before you construct our toolbar, the code for your panel doesn't need to be built with this toolbar (or even be written in TypeScript). Just define the panel in your site's code and just reference it when constructing the toolbar. + +We hope that by having a configurable design will make it easier to onboard this toolbar into your site since you won't need to maintain, build, and export a fork of this project into your site. If you have feedback about onboarding or the configurable design [please open an issue](https://github.com/Microsoft/webperftoolbar/issues/new) so we can discuss it. diff --git a/index.html b/index.html index 990a303..0c84f4f 100644 --- a/index.html +++ b/index.html @@ -7,6 +7,11 @@ +

The toolbar is at the bottom of this page!

+

Ready to test this on a real site? See the instructions on injecting this toolbar via browser plugins.

+

Ready to add it to your page? View the source of this document to see how we add it to the page.

+

Ready to extend the toolbar with your own panel? Follow the instructions.

+