Contributing and reviewing DEA Notebooks

Develop, stable and working branches

The dea-notebooks repository uses 'branches' to manage individuals' notebooks, and to allow easy publishing of notebooks ready to be shared. There are two main types of branches:

• develop branch: The develop branch is the default branch where notebooks are put as they are being prepared to be shared publicly. Changes made to this branch will be merged into the stable branch after we review and test the changes. The develop branch is protected and requires changes to be approved via a 'pull request' and review checklist before they appear on the branch.
• stable branch: The stable branch contains DEA's collection of publicly available notebooks. Notebooks added to this branch will become part of the official DEA documentation and are also published on the DEA Knowledge Hub. The stable branch is protected, and is regularly updated with new content from the develop branch via a 'pull request' (for develop > stable pull requests, merge using the 'Create a merge commit' option).
• Working branches: All other branches in the repository are working spaces for users of dea-notebooks. They have a unique name (typically named after the user, e.g. ClaireK, BexDunn). The notebooks on these branches can be works-in-progress and do not need to be pretty or complete. By using a working branch, it is easy to use scripts and algorithms from dea-notebooks in your own work or share and collaborate on a working version of a notebook or code.

Publishing notebooks to the stable branch

Once you have a notebook that is ready to be published from the develop branch to the DEA Knowledge Hub, you can submit a 'pull request' in the Pull requests tab at the top of the repository. The default pull request template contains a check-list to ensure that all stable branch Jupyter notebooks are consistent and well-documented so they can be understood by future users, and rendered correctly in the DEA Knowledge Hub. Please ensure that as many of these checklist items are complete as possible or leave a comment in the pull request asking for help with any remaining checklist items.

Draft pull requests

For pull requests you would like help with or that are a work in progress, consider using Github's draft pull request feature. This indicates that your work is still a draft, allowing you to get feedback from other DEA users before it is published on the develop branch.

DEA Notebooks template notebook

A template notebook has been developed to make it easier to create new notebooks that meet all the pull request checklist requirements. The template notebook contains a simple structure and useful general advice on writing and formatting Jupyter notebooks. The template can be found here: DEA_notebooks_template.ipynb

Using the template is not required for working branch notebooks but is highly recommended as it will make it much easier to publish any notebooks on develop in the future.

Approving pull requests

Anyone with admin access to the dea-notebooks repository can approve 'pull requests'. You can see a list of the 'pull requests' ready for review in the Pull requests tab at the top of the repository. Click this tab, then click on the open pull request. You will need to review the code before you can approve the request. Ensure that all items in the pull request checklist have been ticked off and incorporated into the notebook. To make changes to someone else's pull request directly, first check out the branch you want to edit (e.g. pull_request_branch):

git pull
git checkout --track origin/pull_request_branch

Commit and push any changes you make, which will become part of the open pull request.

If the notebook meets all the checklist requirements, click the green 'Review' button and click 'Approve' (with an optional comment). You can also 'Request changes' here if any of the checklist items are not complete.

Once the pull request has been approved, you can merge it into the develop branch. Select the 'Squash and merge' option from the drop-down menu to the right of the green 'merge' button. Once you have merged the new branch in, you need to delete the branch. There is a button on the page that asks you if you would like to delete the now merged branch. Select 'Yes' to delete it.