SequenceDiagram/docs/CONTRIBUTING.md

Contributing to Sequence Diagram

Contributions are welcome!

If you find a bug or desire a new feature, feel free to report it in the GitHub issue tracker, or write the code yourself and make a pull request.

Pull requests are more likely to be accepted if the code you changed is tested (write new tests for new features and bug fixes, and update existing tests where necessary).

Getting Started

To get started, you can clone this repository and run:

npm install;
npm start;

This will launch a server in the project directory. You can now open several pages:

• http://localhost:8080/: the main editor (uses minified sources, so you won't see your changes immediately)
• http://localhost:8080/editor-dev.htm: the main editor, using non-minified sources (good for development)
• http://localhost:8080/library.htm: the library sample page (uses minified sources)
• http://localhost:8080/test.htm: browser-based tests
• http://localhost:8080/readme-images.htm: image generation page for the readme file

NOTE: This project uses web modules, which are only supported by recent browsers. In particular, note that FireFox 59 does not support web modules unless a flag is set (FireFox 60 will support them fully). The editor and library page do not require web modules, so should have wider support.

To run the linter, run the command:

npm run lint;

And to rebuild the minified sources, run:

npm run minify;

Currently there are no command-line tests; only the browser tests.

Project Structure

You will find most of the interesting code in /scripts/sequence/*.

The high-level structure is:

• SequenceDiagram (a wrapper class providing an API)
  • Parser (converts source code into a formal structure)
    • Tokeniser (converts source code into tokens for the Parser)
  • Generator (converts the formal structure provided by the Parser into a sort of abstract syntax tree)
  • Renderer (converts the AST provided by the Generator into SVG inside the DOM)
    • components/* (registered with the Renderer to provide layout capability for specific components)
    • themes/* (registered with the Renderer to provide rendering capability through a mix of methods and configurable options)
  • Exporter (provides methods for exporting rendered diagrams as SVG or PNG files)

Useful helpers can also be found in /scripts/core/* and /scripts/svg/*.

The live editor (index.htm & editor-dev.htm) uses the source in /scripts/editor.js and /scripts/interface/*. Other pages use sources in the root of /scripts as their entry-points.

Testing

The testing library used here is Jasmine.

All test files follow the naming convention of <filename>_spec.js, and must be listed in /scripts/spec.js. Linting automatically applies to all files with a .js extension.

You can run the tests by opening test.htm in a browser.

The current state of automated testing is:

• Utilities have a good level of testing
• Parser and Generator stages have a good level of testing
• Rendering methods (SVG generation) have a minimal level of testing; there are some high-level tests in /scripts/sequence/SequenceDiagram_spec.js, and a series of image comparison tests in /scripts/sequence/Readme_spec.js (testing that the readme screenshots roughly match the current behaviour). Finally /scripts/sequence/SequenceDiagram_visual_spec.js uses coarse image comparison to test components and interactions using baseline SVGs from test-images.
• The editor has a minimal level of testing.

If you suspect a failing test is not related to your changes, you can check against the current status of the tests on the master branch: test.htm. If these report a failure in a supported browser, please report it in the issue tracker.

Browser Support

This project officially supports the latest versions of Google Chrome, Mozilla FireFox and Apple Safari (both desktop and iOS). Older browsers, including Internet Explorer, are not supported. Microsoft Edge might work, but this is not actively tested.

In a few places, specific browser workarounds are included, but these are avoided wherever possible.

ECMAScript 6 language features are assumed to be available, and no polyfils are included.

Finalising a Commit

Testing & Linting

Ensure that all unit tests are passing and files pass linting. This can be done by opening test.htm in a browser and running npm run lint in a command window. At a minimum, you should ensure that tests are passing in Google Chrome, but testing in other supported browsers is even better.

Due to the limited testing of SVG rendering, it is also a good idea to open readme-images and scan through to ensure the new rendering of each example is OK. It will show the new rendering as an SVG on the left, as a PNG in the middle, and the old rendering (from /screenshots) on the right.

Minifying

When you have finished your changes, it is good to regenerate the minified library (this is preferred but not required):

npm run minify;

This will update the files in /lib and /weblib. The minified code is a self-contained copy of the /scripts/sequence/SequenceDiagram.js script, with some boiler-plate added to allow loading into a page in a variety of ways.

Screenshots

If your changes affect any of the screenshots in README.md, you can use readme-images, which will automatically extract all sample blocks from the README.md file and generate downloadable PNGs for them with the correct filenames. These should replace the files in the screenshots/ directory.

(I like to aditionally run the screenshots through pngcrush using the flags pngcrush -rem allb -brute -l 9 "<filename>" to reduce the sizes by about half).

The samples in http://localhost:8080/library.htm are dynamically rendered when the user opens the page, so you do not need to update those.

Thank You

Thank you for helping to make this project better!