Guide to using DEA Notebooks with the Github website

Using git to manage files on dea-notebooks is highly recommended because it makes it easy to stay up to date with the latest versions of functions and code, and makes it impossible to lose your work. However, it is possible to do most tasks online on Github by uploading and modifying files directly. Just like the command line git workflow, all changes to files on the develop branch of the repository will need to be submitted as a “pull request” to be reviewed before being added to the develop branch, but the Github will automatically guide you through this process in a reasonably straightforward way.

Getting the entire dea-notebooks directory onto your PC (or the VDI):

1. On dea-notebooks, click "Clone or download" on top-right.
2. Click "Download ZIP" and unzip to your desired location.

Adding a new notebook or file:

1. On Github, browse to the location you would like to upload your file (e.g. dea-notebooks/DEA_datasets).
2. Click "Upload files" and drag and drop or select the notebook/file.
3. At the bottom of the page, add a commit title and description outlining what you have changed. Leave the commit as "Create a new branch for this commit and start a pull request", then hit "Commit changes".
4. Finally, add any extra info on the next "Open a pull request" screen, optionally assign a reviewer, and then "Create pull request".
5. Your changes will be submitted for review, and will be added to the develop branch once accepted.

Modifying an existing notebook and update it in the repository:

1. Edit and save the notebook on your computer without renaming the file.
2. Follow the above "Adding a new notebook or file" instructions. Github should detect any changes to the file, and will update the file on the develop branch once the “pull request” has been reviewed.
3. If you want to make multiple commits before submitting a “pull request”, that's fine: at the "Create a new branch for this commit and start a pull request" stage, edit the branch name (usually something like robbibt-patch-1) to something memorable, press "Commit changes", and then when the "Open a pull request" screen appears, click back to the main dea-notebooks page without creating the “pull request”. On the dea-notebooks page, make sure your new branch is selected using the drop-down "Branch:" menu, and continue to make and commit changes ("Commit directly to the branch" should be automatically selected when you make the commits). When you're finally ready to submit a “pull request”, click the "New pull request" button!
4. Python scripts and plain text like readme files can be edited even more easily by opening the file on Github, then clicking "Edit this file" on the top-right. Add a commit message and submit a “pull request” as above, and the changes will be visible on the develop branch after review.

Deleting existing files:

• Find the file you want to delete in Github, and open it by clicking on the name.
• Up the top-right, select "Delete this file".
• Add a commit message, and submit as a “pull request”. The file will disappear from the develop branch after review.

Important note: To keep your files up to date with the develop branch, ensure that you regularly re-download the repository's zip file. Just make sure you upload or back-up any changed files so that they do not get overwritten by the new files!