From 5a4eb6e73e99903194aab3c006073a3cc717a279 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Mon, 4 Nov 2024 20:11:06 -0800 Subject: [PATCH] doc: Misc improvements * Admonition to be sure to clean up state in setup() * More thorough vetting of new versions in production in server admin page * Typos Resolves #319. --- doc/making-a-visualizer.md | 19 +++++++++++++------ doc/server-administration.md | 29 +++++++++++++++++++++++++++-- 2 files changed, 40 insertions(+), 8 deletions(-) diff --git a/doc/making-a-visualizer.md b/doc/making-a-visualizer.md index b3d88d04..b52d4d3e 100644 --- a/doc/making-a-visualizer.md +++ b/doc/making-a-visualizer.md @@ -204,11 +204,11 @@ checkParameters(), but at least the person running the visualization will be notified. Finally, note that checkParameters is called with _tentative_ parameter values -and is not guaranteed that those parameter values will actually be loaded into -the visualizer. So (a) only access the values through the passed-in `params` -object, not thhrough the visualizer itself, and (b) don't start setting up for -visualization using those values: leave that to one of the set-up functions -discussed below. +and there is no guarantee that those parameter values will actually be loaded +into the visualizer. So (a) only access the values through the passed-in +`params` object, not through the visualizer itself, and (b) don't start +setting up for visualization using those values: leave that to one of the +set-up functions discussed [below](#set-up-the-visualizer-often-used). - **p5 Template:** Make sure that the step size is positive. @@ -282,7 +282,14 @@ that new canvas is a different size than the previous one. However, the visualizer object constructor is not re-run and any data stored in variables in the visualizer object persists. Those defaults mean that you have the option to forgo re-doing expensive pre-computations: if they don't need sketch -access, you can put such calculations in `presketch()`. +access, you can put such calculations in `presketch()`. But the flip side is +that you can't rely on property initializers, your class constructor, or on +(say) checkParameters() to put your other visualizer instance properties in a +"clean" state. For example, if you need some array to be all zeros when you +start drawing your visualization, and previous calls to `draw()` may have +changed some of those array entries, you need to zero it out in `setup()` +because after a parameter change, that's the only preparation function that +will by default be called before going back into the drawing loop. For even greater customization of what happens when, you can override/extend `reset()` from the `P5Visualizer` base class, or you can define a `resized()` diff --git a/doc/server-administration.md b/doc/server-administration.md index 26aa5671..777df100 100644 --- a/doc/server-administration.md +++ b/doc/server-administration.md @@ -21,9 +21,34 @@ subdirectory of the frontscope clone go live instantly. ## How to deploy a new version of frontscope +We presume that we are only going to install the current version of the `main` +branch from the standard repository onto the production machine. This version +has the advantages of having undergone code review and automated unit and +end-to-end tests. Nevertheless, before installing any version, you should +manually make sure it seems to be working properly, one last time: + +1. Make sure you have the latest version of `main` from the standard + repository pulled and checked out on your own machine (or in any case, a + non-production computer). +2. Execute `npm run test:e2e`. +3. Assuming all passes, execute `npm run preview`. +4. Connect to the provided URL, and try a few things with the resulting + Numberscope instance that you've never tried before, and a couple that you + have done many times, to make sure that all seems to be operating. + +When you've done all that, it's OK to install that version on the official +numberscope server. + 1. Log into the numberscope server and `cd ~scope/repos/frontscope`. 2. Execute `sudo -u scope git pull`. 3. Execute `sudo -u scope npm install`. 4. Execute `sudo -u scope npm run build`. -5. Check that the numberscope front end at the primary server URL is working - and serving the updated version of Numberscope. +5. Execute `sudo systemctl restart numberscope`. Note that this step is may + generally be unnecessary for the service to update to the new version, but + is good hygeine for the server in any case. +6. Execture `sudo systemctl status numberscope` to verify that the server + believes the service is running. +7. Check that the numberscope front end at the primary server URL is working + and serving the updated version of Numberscope (by browsing to that URL and + again trying some tasks, especially ones that exercise any new features in + the version you have just installed).