Merge pull request #3605 from blink1073/update-xkcd

Update xkcd tutorial

RELEASE.md

@@ -65,6 +65,7 @@ xckd repo
 - Run `jlpm integrity` to update the `dev_mode` version
 - Commit and push the version update to master
 - Release the other repos as appropriate
+- Update version for binder (see below)
 
 ### Other repos to update
 
@@ -89,17 +90,19 @@ git checkout --orphan name-of-branch
 git rm -rf .
 git clean -dfx
 cookiecutter path-to-local-extension-cookiecutter-ts
-# Fill in the values from the previous branch package.json
-cp -r jupyterlab_xkcd .
+# Fill in the values from the previous branch package.json initial commit
+cp -r jupyterlab_xkcd/ .
 rm -rf jupyterlab_xkcd
 ```
 
 - Create a new PR in JupyterLab.
 - Run through the tutorial in the PR, making commits and updating
 the tutorial as appropriate.
+- Replace the tag references in the tutorial with the new branch number,
+e.g. replace `0.28-` with `0.29-`.
 - Prefix the new tags with the branch name, e.g. `0.28-01-show-a-panel`
-- For the publish section of the readme, use the `LICENSE` and `README`
-files from the previous branch, as well as the `package.json` fields up to
+- For the publish section of the readme, use the `README`
+file from the previous branch, as well as the `package.json` fields up to
 `license`.
 - Push the branch and set it as the default branch for the tutorial repo.
 - Submit the PR to JupyterLab

docs/source/developer/xkcd_extension_tutorial.md

@@ -103,15 +103,16 @@ README.md     package.json  src           style         tsconfig.json
 
 ### Build and install the extension for development
 
-Your new extension project has enough code in it to see it working in your JupyterLab. Run the following commands to install the initial project dependencies and install it in the JupyterLab environment.
+Your new extension project has enough code in it to see it working in your JupyterLab. Run the following commands to install the initial project dependencies and install it in the JupyterLab environment.  We defer building
+since it will be built in the next step.
 
 ```bash
 npm install
 npm run build
-jupyter labextension install .
+jupyter labextension install . --no-build
 ```
 
-After the build completes, open a second terminal.  Run these commands to
+After the install completes, open a second terminal.  Run these commands to
 activate the `jupyterlab-ext` environment and to start a JupyterLab instance
 in watch mode so that it will keep up with our changes as we make them.
 
@@ -278,7 +279,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.30-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.31-01-show-a-panel). Once you've got everything working properly, git commit your changes and carry on.
 
 ```bash
 git add .
@@ -314,7 +315,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.30-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.31-02-show-a-comic) in the reference project. When it's working, make another git commit.
 
 ```bash
 git add .
@@ -386,7 +387,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.30-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.31-03-style-and-attribute). When everything is working as expected, make another commit.
 
 ```bash
 git add .
@@ -508,7 +509,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.30-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.31-04-refactor-and-refresh) to debug. Once it's working properly, commit it.
 
 ```bash
 git add .
@@ -611,7 +612,7 @@ function activate(app: JupyterLab, palette: ICommandPalette, restorer: ILayoutRe
 
 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.30-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.31-05-restore-panel-state) if your extension is misbehaving. Make a commit when the state of your extension persists properly.
 
 ```bash
 git add .
@@ -643,7 +644,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.30-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.31-06-prepare-to-publish) for further debugging.
 
 ![Extension page on npmjs.com](xkcd_tutorial_npm.png)