Codespaces and GitHub

This tutorial will get you familiar with the workflow of getting code from a D2I GitHub repository into codespaces, making a change to the code, and committing that code back to the main code, ready to be reviewed and merged, or cirtiqued for you to keep working on before it is merged. In order to do this, you'll need to be a member of the D2I GitHub and you'll need to have been granted access to our codespaces, which is a platform we pay for per user, and per hour users are active on the platform.

Tutorial Repo

Video version of guide

To get started on this tutorial, you will need to be a member of the D2I GitHub, and have been registered as a codespaces user. If you think you should have been registered but have not yet, email Will at william.levack-payne@eastsussex.gov.uk or, if it is after July 2023, email D2I directly using the contact information in the footer of every page of this site. Once you're set us as a member, head to the repo using this link. This will take you to a page with a list of files, and a big green button in the top right that says Code. The important file for this tutorial is users.py and the important button is the green one. This is pictured below.

If you have had your Codespaces account set up, if you click the Code button, a dropdown will appear. Select the Codespaces tab of this dropdown (pictured below), and then select the Create Codespace on main button. If, for some reason, you don't get this exact same dropdown, select whichever option seems like it would open the code in Codespaces for you.

When you've done this, a new page should pop up, with a dialog box explaining that it is creating you a new Codespace. The length of time this takes depends on the size of the repo and the quality of your internet. When Codespaces opens, you'll have the option to choose a theme for your window. In this tutorial I have chosen the dark theme as it displays better on my personal computer, feel free to choose whichever you like, the only difference should be the colours that are displayed. It is worth noting that if you scoll down and select 'See More Themes...' there is a colour blind theme available for those who may want it. The main page of Codespaces is pictured below. Highlighted by the boxes are the Dark theme I selected, and the users.py file. A pop-up prompt should appear asking if you want to install recommended Python packages, click yes. If it does not appear, or you accidentally close the box, click the highlighted tab on the toolbar to the left of the screen, it looks like three joined squares with another square offset slightly. You'll want to search for and install at least Python and Pylance but you may also want to install Jupyter notebooks.

Once you have installed the necessary packages, select the explorer option in the toolbar on the left of the page, it's the first option below the burger menu, it looks like a standard windows create new file button. This will bring back the list of files from the repo you opened in Codespaces. Navigate to the users.py file. This will bring you to a page of code, as seen in the image below. If you feel that the terminal, the box on the bottom right of the screen, is too large, you can change its size by clicking and dragging the edge down, or close it by clicking the (x) button in the corner of the terminal. If you press the run button (it looks like a play button and is highlighted in the image below), Codespaces will run the code in the file you have opened. In the case of users.py, it will initiate the dictionary of analsyst and where they work, then print the names and workplaces of that dictionary, giving a line by line printout of everyone who has done this tutorial before you in the terminal. If you had closed the terminal, running the code will re-open it to print out the results.

Now we have Python working in our Codespaces, and some code to work on, let's get into the meat of this tutorial: learning how to make a change to the code, and getting that change added to the main code. The first thing we need to do it get a new branch to work on, so that changes we make and commit don't go right into the main code and break it when we commit them. To do this, In the bottom left, click the word main, highlighted in the image below, then click create new branch and name it something sutable. From here on, any changes you make will be made to this new branch and, when you commit them, will be reviewed before being added to the new code. This is so we can check it works and doesn't break anything.

You'll notice there's a dictionary initialised with some D2I team members names and workplaces in it, for you, instead of Data 2 Insight, it will be your LA. Your job is to add your name to this dictionary. I'll add another as an example to help you.

First, click after the last dictionary entry, but on the same line and press enter to create a new line. This new line should be inside the curly braces ({}) that define the dictionary, and there should still be a comma after the entry before yours, indicating that your entry is a new one. Ensure you are indented to write text with the same indent as the other entries in the dictionary. See an an example of this in the image below.

Now you're on a new line, you're ready to enter your name and organisation. I'll add a new line to the list, just for the example. Lets add my friend Dr. Filbert Ake-Analyst who works for the LA, Imaginary Location. We'll create a new dictionary by first giving the name as a key, bounded by quotes (''), then, after a colon, giving the LA bounded by quotes too. Finally, finish the line by leaving a trailing comma. The trailing comma is good practice because it means if code is changed in the future, and new entries are added to the dictionary after your entry, a comma won't need to be added to your entry, marking it as a changed line that needs review. The new line of code will look like this:

'Filbert Ake-Analyst' : 'Imaginary Location',

You can see the full example in the image below.

So now you've made some changes to the code, but people might be working at the same time as you and may have committed changes tot he code too! To make sure your code is up to date with code other people have written, navigate to the source control tab. This is shown in the image below, the button is three circles with lines joining one circle to the other two, there may be a circle with a number in it on top of the button, indicating changes that have been made to the code. If changes have been made to the code that you need to accept, you'll need to use the Sync Changes button, shown below.

Sometimes this can be a bit involved and can require you to enter some code in the terminal, and the process can be very different every time so we can't cover it in this guide, but if you open the output tab of the terminal, it has hints that can help resolving issues. When you sync changes, you'll need to merge them with your current code, as in the image below, which will show you changes between the main code base and your own. As a beginner, it's probably going to be best to either accept incoming changes, which will overwrite yours, or accept both, which may cause conflicts.

If you've had to accept changes, once you've done this, head back to the main users.py file. Run the file and make sure it still works, if not, try and deal with any problems. If you haven't had to sync up any changes, this wont be an issue. Still run your code and make sure it works, printing the list of LA analysts with your name and LA to the terminal when you run it. Once that's done, you're ready to commit your changes. Do this by heading to the version control tab. Enter a comment to explain the change you've made that will make sense to other people reading it, and hit commit. Then click Publish Branch, this pushes your branch live so people can see it.

From here you can then navigate back to GitHub and, in the LA GitHub Codespaces Tutorial repo, from the pull requests tab, you can make a pull request. This is where you go to request that your code be added to the main code. From here, click Compare & pull request to start your request.

From here, check that your pull request is to move your code from your branch into main, you can see this in the image below where the Add-fake-analyst branch has an arrow to the main branch.

Also, make sure you add a sensible description for what your code does. It might not seem necessary now, but it's a good habit to get in to. Then, hit Create pull request. This will show reviewers you've written code you want added. They can then check the code works and either offer corrections to you, or add it to production.

Now you're done! On the next page you may be given the option to merge the pull request yourself, but don't, please leave that up to our expert reviewers. Once the code is merged, everyone will be able to see your name on the users list!