Guide to working with your own copy of the DE Africa Notebooks

Setup

On launch, the sandbox is pre-populated with notebooks from the deafrica-sandbox-notebooks repo. Specifically, with copies of the notebooks on the master branch of the repo. However, for development and review, you'll need your own copy of the deafrica-sandbox-notebooks repo that won't be overwritten by the sandbox's launch behaviour. This process requires forking the DE Africa notebooks repository then adding the forked repositroy to your sandbox environment.

Forking the DE Africa Notebooks repository.

Forking a repository allows you to make a personal copy of a project. To do this, you'll need a GitHub account.

1. Visit the home page of the DE Africa Notebooks repository.
2. Click the Fork button in the top-right corner of the page.

When the fork is complete, you'll be taken to your forked copy of the repository. The header for the repository should now be <username>/deafrica-sandbox-notebooks, rather than digitalearthafrica/deafrica-sandbox-notebooks.

Adding your forked repository to the DE Africa Sandbox

This step will allow you to add the forked repository to the DE Africa Sandbox so that you can make changes to the notebooks, and track your own notebooks.

1. Open and log in to the DE Africa Sandbox

2. Open a terminal from the JupyterLab Launcher (click the "+" New Launcher button on the top-left of JupyterLab, then click "Other > Terminal")

3. Make a new directory to work in by typing:

   mkdir dev

4. You should see the dev directory appear in the file structure. In the terminal, enter the new directory by typing:

   cd dev

5. Clone the forked repository by typing:

   git clone https://github.com/<username>/deafrica-sandbox-notebooks.git

   where <username> is your GitHub username. You can retrieve the full URL by going to your forked repository page, clicking the green "Clone or download" button, and copying the displayed URL.

6. Enter the notebooks directory by typing:

   cd deafrica-sandbox-notebooks

7. Your forked copy will need visibility of the original DE Africa Notebooks repository. This will allow you to update your copy based on changes made by others in the future. Link your forked copy with the original repository by typing git remote add upstream https://github.com/digitalearthafrica/deafrica-sandbox-notebooks.git

Working with the forked repository

You can now work directly in the new deafrica-sandbox-notebooks folder. This section will cover how to add changes from the original repository to your forked copy, commit your changes to your forked repository on GitHub, and how to merge those changes into the original repository, allowing your notebooks to be shared and used by others.

Updating your forked repository

We recommend you do this regularly to receive changes that others have contributed. You must do this before making a pull request back to the original repository (covered below)

1. Get a view of the up-to-date version of the original repository by typing

   git fetch upstream

2. Ensure you're in your repository's master branch by typing

   git checkout master

3. Merge the changes from the original repository by typing

   git merge upstream/master

4. Add these changes to any branch you're working on (see "Starting a new branch" below) by typing

   git checkout <branchname>

   git merge master

   Make sure to replace <branchname> with the name of your branch, e.g. feature-newnotebook

Starting a new branch

Branches are a useful way to keep work self-contained until you're ready to add it to the main repository.

1. Start a new branch (using master as the base) by typing

   git checkout -b <branchname> master

   Make sure to replace <branchname> with the name of your branch, e.g. feature-newnotebook

Working on an existing branch

1. Checkout an existing branch by typing

   git checkout --track upstream/<branchname>

   Make sure to replace <branchname> with the of the branch you want to use, e.g. feature-existingnotebook. You can see a list of branches available on the original repository by typing

   git branch -r

   and noting which ones begin with upstream/

Committing changes and pushing to GitHub

1. See which files you've changed by typing:

   git status

2. See the changes to notebooks by clicking the git extension button in the notebook

3. Add the files you want to commit by typing git add followed by the filenames you want to add or --all to add everything

4. Commit the files with a message by typing:

   git commit -m "Simple commit message"

5. Push your changes by typing git push

   • If this is the first push from this branch, you'll need to type:

   git push --set-upstream origin <branchname>

Creating a pull request

This section is relevant if you want to incorporate changes you've made into the original DE Africa Notebooks repository.

1. When you're ready to add your changes to the original repository, visit the pull requests page on the DE Africa Notebooks repository:

   https://github.com/digitalearthafrica/deafrica-sandbox-notebooks/pulls

2. Click the green "New pull request" button

3. Click the "Compare across forks" link underneath the "Compare Changes" heading

4. Select your forked repository from the "head repository:" dropdown. It will be of the form <username>/deafrica-sandbox-notebooks

5. Select the branch that you want to merge from the "compare:" dropdown.

6. Scroll down to review the changes that you're making.

7. When you're confident that you're adding the right changes, press the green "Create pull request" button.

8. Add a description of your changes, and select people you’d like to review it