From 1f9386d4acedf2bd610aeceda317a6bfb34afe45 Mon Sep 17 00:00:00 2001 From: William Moore Date: Wed, 22 Jan 2025 08:52:51 +0000 Subject: [PATCH 1/4] Add docs/contributing.md --- docs/contributing.md | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 000000000..bf48daeef --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,54 @@ + +Development and Contributing to OMERO.figure +============================================ + + +Development +----------- + +See the [development](https://github.com/ome/omero-figure/blob/master/README.rst#development) +section of the home page for info on getting set up. + +Code notes +---------- + +The JavaScript code is based on the [Backbone.js](http://backbonejs.org/) framework. +We listen for changes to the Model objects, then `render()` the View objects to update the html +using `underscore.js` templates. + +All the front-end code is under `/src/` directory. The `index.html` includes the `js/main.js` as +the JavaScript entry point. This sets up all the Backbone.js objects and listens for changes to the +browser history. + +`Backbone.sync()` is automatically called by Backbone when you `save()` a Model object. We override +that to set `"unsaved": true` on the `FigureModel` object which enables the `Save` button in the UI. +For this reason, you should always call `save()` when updating the `Model` objects E.g. `panel.save('x', 100)` +instead of `panel.set('x', 100)`. + +The `Undo/Redo` queue is also setup in `main.js`. The `UndoManager` listens for changes to the `FigureModel` +and to it's collection of `PanelModel` objects. When a change is detected, the `UndoManager` adds an `Undo/Redo` +action to the queue. It is therefore important to NOT update any model object (e.g. `panel.set('x': 0)`) +when rendering the UI as this will add to the Undo/Redo queue. + +Testing +------- + +When testing a new feature, you should check the following steps: + + - Add several panels to the figure, selecting each in turn and check the feature is working + - For example, editing a particular property of each panel + - Select several panels at once, each with different values of this property + - Check it is the displayed correctly and batch-editing is enabled if appropriate + - Test that Undo and Redo work as expected. + - Is the Save button enabled when you make a change? + - If you refresh the page after Saving, does the change persist? + - When you export the figure to PDF and TIFF, is this feature handled correctly? + - Make sure the export script can handle panels where this new property is missing: `panel.get('property', default)` + +Contributing +------------ + +Use: `Fixes #123` to reference an issue in the PR description. This will automatically close the issue when the PR is merged. + +Adding a screenshot to the PR description can be helpful, both for initial review but also for +users coming to the PR from the release Changelog. \ No newline at end of file From 4fb41504214182bba3e61cf2b609bf0d1fbb7e53 Mon Sep 17 00:00:00 2001 From: William Moore Date: Wed, 22 Jan 2025 09:26:56 +0000 Subject: [PATCH 2/4] Add Planning section to contributing.md --- docs/contributing.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/contributing.md b/docs/contributing.md index bf48daeef..ec4a82b63 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -2,6 +2,12 @@ Development and Contributing to OMERO.figure ============================================ +Planning +-------- + +Before starting to work on a new feature, you are encouraged to create an Issue and to +add some outline of the expected work required. This is helpful to organise your +thoughts but can also allow others to contribute. Development ----------- From 259273b6dcc1a0b4f44828ccab19553940f765b5 Mon Sep 17 00:00:00 2001 From: William Moore Date: Wed, 22 Jan 2025 16:43:08 +0000 Subject: [PATCH 3/4] add .github/PULL_REQUEST_TEMPLATE.md --- .github/PULL_REQUEST_TEMPLATE.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..d380d7814 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,5 @@ + +[Description of PR] + +Please see https://github.com/ome/omero-figure/blob/master/docs/contributing.md +for a testing checklist. From 12437de3694fec212ecf8badd1e2a068b436a529 Mon Sep 17 00:00:00 2001 From: William Moore Date: Fri, 24 Jan 2025 11:48:03 +0000 Subject: [PATCH 4/4] Add a Dev server section to contributing.md --- README.rst | 2 ++ docs/contributing.md | 25 ++++++++++++++++++++----- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index f07b65f31..435475fec 100644 --- a/README.rst +++ b/README.rst @@ -134,6 +134,8 @@ above. If using *Option 1*, you need to *replace* the existing script: Development ----------- +See `docs/contributing.md` for information on code layout and other details. + We use `vite.js `_ to build and serve the app during development. Install Node from https://nodejs.org, then: diff --git a/docs/contributing.md b/docs/contributing.md index ec4a82b63..5a3f2153f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -36,20 +36,35 @@ and to it's collection of `PanelModel` objects. When a change is detected, the ` action to the queue. It is therefore important to NOT update any model object (e.g. `panel.set('x': 0)`) when rendering the UI as this will add to the Undo/Redo queue. +Dev server and build +-------------------- + +The application can be served from the `vite.js` dev server during development at `http://localhost:8080/`. +This includes "hot module reload" of edited code without needing to refresh the page. +However, the app doesn't have any OMERO server context when it is served like this, such as the logged-in user details. +For this reason, some features won't work as expected, such as the default filtering of Files by user. +The app can `GET` data via a cross-origin request to your `omero-web` server at `http://localhost:4080/` +(this URL can be edited in `index.html`). However, cross-origin `POST` requests are not expected to work. + +When the compiled html is served by the `omero-web` OMERO.figure app, we use simple `string.replace()` +to inject OMERO server information into the `index.html` page. This includes the logged-in user details, +the omero-web server address and various config values. + Testing ------- When testing a new feature, you should check the following steps: - - Add several panels to the figure, selecting each in turn and check the feature is working - - For example, editing a particular property of each panel - - Select several panels at once, each with different values of this property - - Check it is the displayed correctly and batch-editing is enabled if appropriate + - Run `$ npm build` and test from your `omero-web` deployment instead of the `vite.js` dev server. + - Check that you can open old figures (created before your feature was added). + - Add several panels to the figure, selecting each in turn and check the feature is working (for example, editing a particular property of each panel). + - Select several panels at once, each with different values of this property. + - Check it is the displayed correctly and batch-editing is enabled if appropriate. - Test that Undo and Redo work as expected. - Is the Save button enabled when you make a change? - If you refresh the page after Saving, does the change persist? - When you export the figure to PDF and TIFF, is this feature handled correctly? - - Make sure the export script can handle panels where this new property is missing: `panel.get('property', default)` + - Make sure the export script can handle panels where this new property is missing: E.g. use `panel.get('property', default)`. Contributing ------------