Add contributing guidance
This commit is contained in:
David Evans
parent
baa0a025b0
commit
ea9374ecd5
23
README.md
23
README.md
|
|
@ -303,24 +303,5 @@ If you find a bug or desire a new feature, feel free to report it in
|
|||
the [GitHub issue tracker](https://github.com/davidje13/SequenceDiagram/issues),
|
||||
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). You can make sure the tests and linter
|
||||
are passing by opening test.htm
|
||||
|
||||
Note: the linter can't run from the local filesystem, so you'll need to
|
||||
run a local HTTP server to ensure linting is successful. One option if
|
||||
you have NPM installed is:
|
||||
|
||||
```shell
|
||||
npm run serve;
|
||||
```
|
||||
|
||||
It is also good to rebuild the minified library when committing:
|
||||
|
||||
```shell
|
||||
npm run minify;
|
||||
```
|
||||
|
||||
The current status of the tests on the master branch can be checked at
|
||||
[test.htm](https://davidje13.github.io/SequenceDiagram/test.htm)
|
||||
For more details on contributing, see the
|
||||
[CONTRIBUTING.md file](docs/CONTRIBUTING.md).
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<Workspace
|
||||
version = "1.0">
|
||||
<FileRef
|
||||
location = "container:docs">
|
||||
</FileRef>
|
||||
<FileRef
|
||||
location = "container:scripts">
|
||||
</FileRef>
|
||||
|
|
@ -23,7 +26,7 @@
|
|||
location = "container:package.json">
|
||||
</FileRef>
|
||||
<FileRef
|
||||
location = "container:readme_images.htm">
|
||||
location = "container:readme-images.htm">
|
||||
</FileRef>
|
||||
<FileRef
|
||||
location = "container:README.md">
|
||||
|
|
|
|||
|
|
@ -0,0 +1,155 @@
|
|||
# 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](https://github.com/davidje13/SequenceDiagram/issues),
|
||||
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 simply open
|
||||
`index.htm` or `library.htm` in your browser. You do not need any build
|
||||
tooling, and you do not need to run a local server. You can also run
|
||||
the unit tests (but not the linter) by opening `test.htm`.
|
||||
|
||||
In order to run the linter, you will need to serve the files using a
|
||||
local server. When opened in this way, `test.htm` will run both the
|
||||
unit tests and the linter. If you have `node` & `npm` installed, this
|
||||
is easy to do:
|
||||
|
||||
```shell
|
||||
npm install;
|
||||
npm run serve;
|
||||
```
|
||||
|
||||
The tests and linter will now be available at
|
||||
[http://localhost:8080/test.htm](http://localhost:8080/test.htm).
|
||||
|
||||
When running using a local server, you can also use the
|
||||
[editor-dev](http://localhost:8080/editor-dev.htm) resource to test
|
||||
changes you make to the code. This page uses the non-minified source,
|
||||
meaning your changes will be available immediately (unlike index.htm
|
||||
which requires you to run the minifier first).
|
||||
|
||||
## 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](https://jasmine.github.io/).
|
||||
|
||||
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 which are loaded during testing.
|
||||
|
||||
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 poor level of testing;
|
||||
there are some high-level tests in
|
||||
`/scripts/sequence/SequenceDiagram_spec.js` but many component types
|
||||
are not tested at all during rendering beyond ensuring that they can
|
||||
be used without throwing exceptions. The same applies to themes.
|
||||
* 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](https://davidje13.github.io/SequenceDiagram/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. 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](http://localhost:8080/readme-images.htm) 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):
|
||||
|
||||
```shell
|
||||
npm run minify
|
||||
```
|
||||
|
||||
This will update the files in `/lib`. 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](http://localhost:8080/readme-images.htm), 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](https://pmt.sourceforge.io/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](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!
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
Details of your pull request here - if you have fixed an issue, please
|
||||
reference it with #issue-number.
|
||||
|
||||
Checklist: (tick with [x])
|
||||
|
||||
- [ ] Any new spec files are listed in `scripts/specs.js`.
|
||||
- [ ] Tests & linting are passing in Google Chrome.
|
||||
- [ ] No dead code is left behind.
|
||||
- [ ] (optional): `minify` has been run.
|
||||
- [ ] (optional): Any relevant screenshots have been updated.
|
||||
- [ ] I agree to release my code under the license of this project (LGPL-3.0).
|
||||
|
|
@ -591,8 +591,9 @@ for all types.
|
|||
|
||||
<p>
|
||||
There are quite a lot of sequence diagram drawing tools available. If this one
|
||||
doesn't fit your needs for whatever reason, you might want to take a look at the
|
||||
alternatives:
|
||||
doesn’t fit your needs for whatever reason, you might want to take a look
|
||||
at the alternatives: (but also feel free to raise feature requests in the
|
||||
<a href="https://github.com/davidje13/SequenceDiagram/issues" target="_blank">issue tracker</a>!)
|
||||
</p>
|
||||
<ul>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue