Edit a DEA Notebook

This guide will show you the recommended way for editing a DEA Notebook and contributing to the dea-notebooks repository. It involves editing the content within the Sandbox which is an interactive online workspace where you can edit and run Jupyter Notebooks. Advanced users can use the NCI instead of the Sandbox.

📘 Making a minor edit?
You can save time by instead editing using the Github website.

Edit a Notebook

You can edit a Notebook easily using the Sandbox — you don't need to install anything to your computer. However, you must have a basic understanding of git and Github.

1. Log in or sign up to the DEA Sandbox.

   The sandbox will contain the Notebooks from the stable branch of the dea-notebooks repository. Learn more about the DEA Sandbox.

   ⚠️ Warning
   Don't edit these Notebooks directly because your changes will not be saved!

2. Click the "+" (plus) icon in the top-left to open the Launcher then click to open the Terminal. This is a Linux terminal for your sandbox environment.

3. Navigate to the home directory then clone the 'dea-notebooks' repository's develop branch into a new folder called dev. Then, enter the new dev folder.

   cd ~
   
   git clone --depth 1 --branch develop https://github.com/GeoscienceAustralia/dea-notebooks.git dev
   
   cd dev

4. Create a new git branch with a name of your choice.

   git checkout -b your-branch  # Change this to your branch name

5. In the sidebar of the sandbox, click to open your dev folder, then open any notebook. For example, click How_to_guides then double-click Analyse_multiple_polygons.ipynb to open it in a new tab.

6. Edit the notebook using the interactive editor. Learn how to edit Jupyter Notebooks in the interactive editor.

7. Switch back to the Terminal tab then commit and push the changes to your branch. But first, you will need to configure a git email and name.

   git config --global user.email "[email protected]"  # Change this to your email
   git config --global user.name "Your Name"  # Change this to your name
   
   git status
   git add --all
   git commit -m "Edited the notebook: Analyse multiple polygons"  # Change this to your commit message
   git push -u origin your-branch  # Change this to your branch name

   You will then need to enter your Github username and password. If you do not have a Github account, sign up here.

   Troubleshooting: Permission denied

   If this is your first time contributing to the 'dea-notebooks' repository, you will probably receive the error: remote: Permission to GeoscienceAustralia/dea-notebooks.git denied

   To resolve this, an existing member of the 'dea-notebooks' repository will need to send you an invite. They must go to dea-notebooks > Settings > Collaborators and Teams > Search by username ... > Add Collaborator.

   Troubleshooting: Invalid username or password

   You may encounter the following error.

   remote: Invalid username or password.
   fatal: Authentication failed for 'https://github.com/GeoscienceAustralia/dea-notebooks.git/'
   

   If so, create a personal access token with the repo scope. Save the token to a secure location then retry pushing to the repo except when it asks for your password, enter the token instead. For example ...

   git push -u origin your-branch
   
   Username: your-username
   Password: 3i4htrou3fgffgyy45tysiduhg6779yho87rtiouhihrego7wery

8. Continue editing the notebooks and pushing your changes to the branch.

9. Once you are ready to publish your changes, create a pull request to merge your branch into the develop branch.

   1. Open the dea-notebooks repository > click Pull requests > click New pull request.

   2. Click the second dropdown and select your branch.

      

   3. Click Create pull request then follow the instructions in Github to create the pull request.

   4. Post your pull request in our Slack channel for feedback.

   Troubleshooting: Can’t automatically merge

   This means that you will need to merge the latest develop branch into your branch and resolve any 'merge conflicts'.

   1. In the Sandbox's Terminal, run the following commands.

      git checkout develop
      git pull
      git checkout your-branch
      git merge develop

      You will be prompted to name the merge commit. Accept the default name by pressing Esc on your keyboard, then type :wq followed by Enter. (This prompt uses the Vim editor.)

   2. Resolve any merge conflicts that occur.

   3. Push to your branch.

      git push

   4. Your pull request should update to say that it is able to be merged.

10. A reviewer must review your pull request before approving and merging it. Reviewers can follow this guide to review pull requests. They must ensure that all the checklist items have been satisfied.

11. After your pull request is merged, please wait some time until your changes display in new Sandboxes and on the Notebooks section of the DEA Knowledge Hub.

Advanced: Using the NCI

The above instructions should work for setting up Git on both the DEA Sandbox and the NCI (via the Virtual Desktop Infrastructure or VDI). However, there are some important things to keep in mind:

• To get started with dea-notebooks using git on the NCI, the first step is to clone this repository to a suitable location. This will most likely be a location you can access on the VDI, so you can easily work with your notebooks. Note that this repo is likely to become quite large, so make sure you have enough space in the location you clone the repository to (i.e. probably not your home directory, but a directory on /g/data/ should be perfect).
• If you haven't used Git on the VDI before, you will need to set up some SSH keys before you will be able to clone the repository. To set up the SSH keys, follow these instructions to generate a new SSH key in your home directory on the VDI. You will need to generate the key, register it with your ssh agent, and then add the newly generated id_rsa.pub public key to your GitHub account.

Troubleshooting: Firefox web browser freezing

Some VDI users have encountered an issue with the Firefox browser freezing with an A webpage is slowing down your browser error when attempting to launch JupyterLab. This seems to occur when there is a large Git repository (e.g. DEA Notebooks) in JupyterLab's working directory that causes issues with the jupyterlab_git extension. A workaround for this issue is to disable this extension: to do this, right click on the "Digital Earth Australia" icon on your desktop, click "Properties", and replace the text in "Command:" with the following:

bash -c "module use /g/data/v10/public/modules/modulefiles && module load dea && module load otps && module load ffmpeg && jupyter serverextension disable jupyterlab_git && jupyter lab --notebook-dir=~ --NotebookApp.default_url=lab/tree/dea-notebooks"

Alternatively, run the following line before launching JupyterLab (e.g. in a shell script or on the command line):

jupyter serverextension disable jupyterlab_git

Troubleshooting: Errors after VDI release on 26 October 2020

Some VDI users have experienced errors after the new VDI release on 26 October 2020. Check out the VDI FAQ for help on this issue