Misc updates

add release instructions in root README enhance the library's package.json add README for npm package massaged,Fixed linter warnings in documentation.md, README Signed-off-by: Marc Dumais <[email protected]>
eclipse-cdt-cloud · Mar 1, 2024 · 1374961 · 1374961
1 parent 126b406
commit 1374961
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,9 @@
-# Time Graph
+# Time Graph - Developer's README
 
 [![Gitpod - Code Now][gitpod-icon-small]][gitpod-link]
 [![Build Status][build-status-icon]][build-status-link]
 
+
 A time graph / gantt chart library for large data (e.g. traces)
 
 To build, from the root type `yarn`
@@ -60,22 +61,57 @@ You can view an example [here](./timeline-chart/src/layer/__tests__/time-graph-c
 2. It is important to re-construct the timeline chart before each test to make sure the results are consistent.
 3. The tests themselves only print out the results and don't compare them to an actual value, because the threshold depends on the environment it runs. Therefore, make sure to output the performance measurement to the output console, so that it can be viewed once the tests finished running.
 
-## Test coverage
+### Test coverage
 
 The following command prints a coverage report to the terminal. As of now it covers all typescript files of the project, including those that are not supposed to have tests.
 
 ```shell
 yarn test --coverage --collectCoverageFrom='src/**/*.ts'
 ```
 
+## Release/publish
+
+Publishing of npm package and creating GitHub releases / git tags, all happen on GitHub CI.
+
+### Publish next package
+
+A `next` package is automatically published to `npm` every time a PR is merged.
+
+### publish latest / release
+
+Whenever a new release is desired, including publishing a corresponding `latest` package to `npm`, it can be triggered through a PR. The following has to be done:
+
+Create a new branch for your PR. e.g. 
+```bash
+git branch new-release && git checkout new-release
+```
+
+Then decide if the release shall be a `Major`, `Minor` or `Patch` release and use the corresponding command below to step packages versions, according to the release type. A new release commit will be created:
+
+``` bash
+yarn version:major
+# or
+yarn version:minor
+# or
+yarn version:patch
+```
+
+Modify the _version tag_ in file `./RELEASE`, to match the new release. Amend the release commit to include this change:
+
+```bash
+git add RELEASE && git commit --amend
+```
+
+Finally, push the branch and use it to create a PR. When the PR is merged, a GitHub release should be created with auto-generated release notes, as well as a git tag. Then the `publish-latest` CI job should trigger and if everything goes well, publish the new version of the package to `npm`.
+
 [build-status-icon]: https://github.com/eclipse-cdt-cloud/timeline-chart/workflows/CI-CD/badge.svg?branch=master
 [build-status-link]: https://github.com/eclipse-cdt-cloud/timeline-chart/actions?query=branch%3Amaster
 [contributing]: CONTRIBUTING.md
 [documentation]: https://github.com/eclipse-cdt-cloud/timeline-chart/blob/master/doc/documentation.md
 [gitpod-icon-large]: https://gitpod.io/button/open-in-gitpod.svg
 [gitpod-icon-small]: https://img.shields.io/badge/Gitpod-code%20now-blue.svg?longCache=true
 [gitpod-link]: https://gitpod.io#https://github.com/eclipse-cdt-cloud/timeline-chart
-[sample-app]: https://github.com/theia-ide/theia-timeline-extension
+[sample-app]: https://github.com/eclipse-cdt-cloud/timeline-chart/blob/master/example/
 [screenshot-1]: https://raw.githubusercontent.com/eclipse-cdt-cloud/timeline-chart/master/doc/images/screenshot1-0.0.1.png
 [screenshot-2]: https://raw.githubusercontent.com/eclipse-cdt-cloud/timeline-chart/master/doc/images/screenshot2-0.0.1.png
 [trace-extension]: https://github.com/eclipse-cdt-cloud/theia-trace-extension
diff --git a/doc/documentation.md b/doc/documentation.md
@@ -1,31 +1,38 @@
-# General Scope
+# Timeline-chart Library
+
 * The library is entirely client side, relying on the browser API.
 * Time is measured using number, so any kind of x measure unit can be used. 
 * A function translating numbers into human readable form for labels and hovers can be provided by the library user.
 * API for interaction with elements that will allow to register key and mouse listeners.
 * The components are styleable. Those parts that are implemented in HTML allow CSS for styling. The timeline view\u2019s contents (gantt chart) provide an API for styling
 
-# Components
-## Time Controller
+## Components
+
+### Time Controller
+
 * A central time controller that manages time-related properties, like the total time range, viewed range, time cursor positions.
 * It provides API for setting, reading and syncing the individual properties
 
-## Time Cursor
+### Time Cursor
+
 * Time Cursor T1 and optionally T2 are displayed as a vertical line spanning all rows. Range between T1 and T2 will be highlighted. Styling is configurable through CSS.
 * Time range selection (or range selection) has full read/write/listen API.
 * Rendering is configurable through CSS and separated from the actual data.
 Setting cursor T1 is doable by clicking anywhere in the main area. A mouse click while holding shift will set T2.
 View Port positions (use to scroll and zoom) has full read/write/listen API.
 
-## Time Axis
+### Time Axis
+
 A reusable time axis component, that can be used independently of the other components. It syncs with a time controller and allows the user to change the controllers values (zooming, scrolling, setting cursors)
+
 * The time axis is separated and usable alone, such that other widgets can render below and sync with the same time axis.
 * It is styleable through CSS.
 * A time axis controller is used to sync any number of widgets, so that scrolling in any of the timeline charts or the time axis will scroll all others accordingly.
 * Clicking and dragging on the time axis will increase/decrease the zoom
 * The view is connected to a time controller instance and sync its viewport, zoom level cursors bi-directionally
 
-## Timeline View
+### Timeline View
+
 * Shows data as a gantt chart on multiple rows. 
 * Optional labels can be shown in each state of each row.
 * Optional marker symbols can be drawn over the states.
@@ -43,7 +50,8 @@ A reusable time axis component, that can be used independently of the other comp
 * Horizontal zooming can be cancelled by pressing the `esc` button while zooming using the right click + drag.
 * The view is connected to a time controller instance and synchronizes its viewport, zoom level cursors bi-directionally.
 
-## Data Model
+### Data Model
+
 * Library user can configure a data model provider which gets asked for data lazily depending on the viewport.
 * Data is prefetched for x and y dimensions to make scrolling smoother.
 * Data can be fetched for a given resolution, so the provider can optimize the amount of data provided.

diff --git a/timeline-chart/README.md b/timeline-chart/README.md
@@ -1,14 +1,19 @@
-## Description
+# timeline-chart
 
-A time graph / gantt chart library for large data (e.g. traces).
+A time graph / gantt chart library for large data (e.g. traces)
 
-## Additional Information
+## Documentation
 
-- [Documentation](https://github.com/eclipse-cdt-cloud/timeline-chart/blob/master/doc/documentation.md): Detailed description of the timeline-chart library and its components.
-- [Theia Trace Extension](https://github.com/eclipse-cdt-cloud/theia-trace-extension): A reference application that uses the timeline-chart library.
+For detailed description of the `timeline-chart` library and it's components see [here][documentation].
+
+See also this [example application] that makes use of it.
 
 ## Screenshots
 
-![timeline-chart](https://raw.githubusercontent.com/eclipse-cdt-cloud/timeline-chart/master/doc/images/screenshot1-0.0.1.png)
-![timeline-chart](https://raw.githubusercontent.com/eclipse-cdt-cloud/timeline-chart/master/doc/images/screenshot2-0.0.1.png)
+![timeline-chart][screenshot-1]
+![timeline-chart][screenshot-2]
 
+[example application]: https://github.com/eclipse-cdt-cloud/timeline-chart/tree/master/example
+[documentation]: https://github.com/eclipse-cdt-cloud/timeline-chart/blob/master/doc/documentation.md
+[screenshot-1]: https://raw.githubusercontent.com/eclipse-cdt-cloud/timeline-chart/master/doc/images/screenshot1-0.0.1.png
+[screenshot-2]: https://raw.githubusercontent.com/eclipse-cdt-cloud/timeline-chart/master/doc/images/screenshot2-0.0.1.png
diff --git a/timeline-chart/package.json b/timeline-chart/package.json
@@ -1,6 +1,13 @@
 {
   "name": "timeline-chart",
   "version": "0.2.0",
+  "description": "A time graph / gantt chart library for large data (e.g. traces)",
+  "keywords": [
+    "gantt",
+    "timeline",
+    "tracing",
+    "trace"
+  ],
   "license": "MIT",
   "scripts": {
     "build": "tsc",
@@ -26,5 +33,13 @@
     "jest-canvas-mock": "^2.3.1",
     "rimraf": "latest",
     "ts-jest": "^29.0.0"
+  },
+  "homepage": "https://github.com/eclipse-cdt-cloud/timeline-chart",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-cdt-cloud/timeline-chart"
+  },
+  "bugs": {
+    "url": "https://github.com/eclipse-cdt-cloud/timeline-chart/issues"
   }
 }