Update xkcd tutorial and release notes (#3211)

* Update xkcd tutorial and release notes

More release notes cleanup

reorganize

cleanup [ci skip]

more cleanup [ci skip]

Fix update dep script

simplify [ci skip]

cleanup [ci skip]

Update RELEASE.md

* clean up update and remove deps scripts

RELEASE.md

@@ -8,7 +8,7 @@ This document guides a contributor through creating a release of JupyterLab.
 Review ``CONTRIBUTING.md``. Make sure all the tools needed to generate the
 built JavaScript files are properly installed.
 
-## Create the release
+## Creating a full release
 
 We publish the npm packages, a Python source package, and a Python universal binary wheel.  We also publish a conda package on conda-forge (see below).
 See the Python docs on [package uploading](https://packaging.python.org/guides/tool-recommendations/)
@@ -25,7 +25,7 @@ requirement from getting a conflict.
 npm run publish
 ```
 
-### Publish the python package
+### Publish the Python package
 
 - Update `jupyterlab/_version.py` with an `rc` version
 - Prep the static assets for release:
@@ -35,7 +35,7 @@ npm run build:static
 ```
 
 - Commit and tag and push the tag
-- Create the python release artifacts:
+- Create the Python release artifacts:
 
 ```bash
 rm -rf dist
@@ -51,33 +51,41 @@ twine upload dist/*
   - The build will fail if we forget to include `style/` in the `files:`
     of a package (it will fail on the `jupyter lab build` command because
     webpack cannot find the referenced styles to import.
+- Update the other repos listed below
+- Update the extension examples listed below
+- Update the xkcd tutorial
 - Update `jupyterlab/_version.py` with a final version 
 - Make another Python release
-- Get the sha256 hash for conda-forge release:
-
-```bash
-shasum -a 256 dist/*.tar.gz
-```
-
-### Publish to conda-forge
-- Fork https://github.com/conda-forge/jupyterlab-feedstock
-- Create a PR with the version bump
-- Update `recipe/meta.yaml` with the new version and md5 and reset the build number to 0.
-
-### Update the cookie cutters as necessary
-- Update https://github.com/jupyterlab/extension-cookiecutter-js
-- Update https://github.com/jupyterlab/extension-cookiecutter-ts
-- Update https://github.com/jupyterlab/mimerender-cookiecutter
-
-### Update the extension examples
+- Create a branch for the release and push to GitHub
+- Merge the PRs on the other repos and set the default branch of the
+xckd repo
+- Publish to conda-forge (see below)
+- Update `jupyterlab/_version.py` with a `dev` version
+- Commit and push the version update to master
+- Release the other repos as appropriate
+
+### Other repos to update
+- https://github.com/jupyterlab/extension-cookiecutter-js
+- https://github.com/jupyterlab/extension-cookiecutter-ts
+- https://github.com/jupyterlab/mimerender-cookiecutter
+- https://github.com/jupyterlab/mimerender-cookiecutter-ts
+- https://github.com/jupyterlab/jupyter-renderers
+- https://github.com/jupyterhub/jupyterlab-hub
+
+
+### Extension examples to update
 - https://github.com/jupyterlab/jupyterlab/blob/master/docs/notebook.md#adding-a-button-to-the-toolbar
 
-### Update the xkcd tutorial
+
+### Updating the xkcd tutorial
 - Create a new empty branch in the xkcd repo.
 
 ```bash
-git checkout --orphan NEWBRANCH
+git checkout --orphan name-of-branch
 git rm -rf .
+cookiecutter path-to-local-extension-cookiecutter-ts
+cp -r jupyterlab_xkcd/ .
+rm -rf jupyterlab_xkcd
 ```
 
 - Create a new PR in JupyterLab.
@@ -90,21 +98,28 @@ files from the previous branch, as well as the `package.json` fields up to
 - Push the branch and set it as the default branch for the tutorial repo.
 - Submit the PR to JupyterLab
 
-### Set master back to dev version
-- Create a branch for the release and push to github.
-- Update `jupyterlab/_version.py` with a `dev` version.
-- Commit and push the version update.
+
+### Publishing to conda-forge
+- Get the sha256 hash for conda-forge release:
+
+```bash
+shasum -a 256 dist/*.tar.gz
+```
+
+- Fork https://github.com/conda-forge/jupyterlab-feedstock
+- Create a PR with the version bump
+- Update `recipe/meta.yaml` with the new version and md5 and reset the build number to 0.
 
 
-## Making a patch release of a JavaScript Package
-- Create a branch based on the last Python release if one does not exist.
-- Create a PR against that branch with the changes.
-- Merge the PR.
-- Run the following script from the branch to make a patch release, 
-where the package is in `/packages/packageFolder`:
+## Making a patch release of a JavaScript package
+- Backport the change to the previous release branch
+- Make a new PR against master
+- Run the following script, where the package is in `/packages/package-folder-name`:
 
 ```bash
-npm run patch:release packageFolder
+npm run patch:release package-folder-name
 ```
 
 - Push the resulting commit and tag.
+- Backport the release update to the previous release branch
+- Create a new Python release on the previous branch

buildutils/src/remove-dependency.ts

@@ -39,10 +39,9 @@ function handlePackage(packagePath: string): void {
   }
 
   // Update dependencies as appropriate.
-  if (name in data['dependencies']) {
-    delete data['dependencies'][name];
-  } else if (name in data['devDependencies']) {
-    delete data['devDependencies'][name];
+  for (let dtype in ['dependencies', 'devDependencies']) {
+    let deps = data[dtype] || {};
+    delete deps[name];
   }
 
   // Write the file back to disk.

buildutils/src/update-dependency.ts

@@ -50,10 +50,11 @@ function handlePackage(packagePath: string): void {
   }
 
   // Update dependencies as appropriate.
-  if (name in data['dependencies']) {
-    data['dependencies'][name] = specifier;
-  } else if (name in data['devDependencies']) {
-    data['devDependencies'][name] = specifier;
+  for (let dtype in ['dependencies', 'devDependencies']) {
+    let deps = data[dtype] || {};
+    if (name in deps) {
+      deps[dtype] = specifier;
+    }
   }
 
   // Write the file back to disk.

docs/xkcd_extension_tutorial.md

@@ -265,7 +265,7 @@ Build your extension again using `npm run build` (unless you are using
 
 ![Empty xkcd extension panel](xkcd_tutorial_empty.png)
 
-If your widget is not behaving, compare your code with the reference project state at the [01-show-a-panel tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.28-01-show-a-panel). Once you've got everything working properly, git commit your changes and carry on.
+If your widget is not behaving, compare your code with the reference project state at the [01-show-a-panel tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.29-01-show-a-panel). Once you've got everything working properly, git commit your changes and carry on.
 
 ```bash
 git add .
@@ -306,7 +306,7 @@ Rebuild your extension if necessary (`npm run build`), refresh your browser tab,
 
 Note that the comic is not centered in the panel nor does the panel scroll if the comic is larger than the panel area. Also note that the comic does not update no matter how many times you close and reopen the panel. You'll address both of these problems in the upcoming sections.
 
-If you don't see a comic at all, compare your code with the [02-show-a-comic tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.28-02-show-a-comic) in the reference project. When it's working, make another git commit.
+If you don't see a comic at all, compare your code with the [02-show-a-comic tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.29-02-show-a-comic) in the reference project. When it's working, make another git commit.
 
 ```bash
 git add .
@@ -378,7 +378,7 @@ sure you can scroll the panel over the entire area of the comic.
 
 ![Styled xkcd panel with attribution](xkcd_tutorial_complete.png)
 
-If anything is misbehaving, compare your code with the reference project [03-style-and-attribute tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.28-03-style-and-attribute). When everything is working as expected, make another commit.
+If anything is misbehaving, compare your code with the reference project [03-style-and-attribute tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.29-03-style-and-attribute). When everything is working as expected, make another commit.
 
 ```bash
 git add .
@@ -511,7 +511,7 @@ const extension: JupyterLabPlugin<void> = {
 
 Make sure you retain the `export default extension;` line in the file. Now build the extension again and refresh the JupyterLab browser tab. Run the *Random xkcd comic* command more than once without closing the panel. The comic should update each time you execute the command. Close the panel, run the command, and it should both reappear and show a new comic.
 
-If anything is amiss, compare your code with the [04-refactor-and-refresh tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.28-04-refactor-and-refresh) to debug. Once it's working properly, commit it.
+If anything is amiss, compare your code with the [04-refactor-and-refresh tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.29-04-refactor-and-refresh) to debug. Once it's working properly, commit it.
 
 ```bash
 git add .
@@ -624,7 +624,7 @@ const extension: JupyterLabPlugin<void> = {
 
 Rebuild your extension one last time and refresh your browser tab. Execute the *Random xkcd comic* command and validate that the panel appears with a comic in it. Refresh the browser tab again. You should see an xkcd panel appear immediately without running the command. Close the panel and refresh the browser tab. You should not see an xkcd tab after the refresh.
 
-Refer to the [05-restore-panel-state tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.28-05-restore-panel-state) if your extension is misbehaving. Make a commit when the state of your extension persists properly.
+Refer to the [05-restore-panel-state tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.29-05-restore-panel-state) if your extension is misbehaving. Make a commit when the state of your extension persists properly.
 
 ```bash
 git add .
@@ -656,7 +656,7 @@ Now run the following command to publish your package:
 npm publish --access=public
 ```
 
-Check that your package appears on the npm website. You can either search for it from the homepage or visit `https://www.npmjs.com/package/@your-username/jupyterlab_xkcd` directly. If it doesn't appear, make sure you've updated the package name properly in the `package.json` and run the npm command correctly. Compare your work with the state of the reference project at the [06-prepare-to-publish tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.28-06-prepare-to-publish) for further debugging.
+Check that your package appears on the npm website. You can either search for it from the homepage or visit `https://www.npmjs.com/package/@your-username/jupyterlab_xkcd` directly. If it doesn't appear, make sure you've updated the package name properly in the `package.json` and run the npm command correctly. Compare your work with the state of the reference project at the [06-prepare-to-publish tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/0.29-06-prepare-to-publish) for further debugging.
 
 ![Extension page on npmjs.com](xkcd_tutorial_npm.png)