Minor fixes, add another two rough lesson ports

Author: steve-crouch

config.yaml

@@ -74,6 +74,18 @@ episodes:
 - 12-running-vscode.md
 - 13-code-editor.md
 - 14-running-debugging.md
+- 20-introduction.md
+- 21-setup.md
+- 22-example-code.md
+- 23-analysing-code.md
+- 24-linter-advanced.md
+- 30-introduction.md
+- 31-setup.md
+- 32-example-code.md
+- 33-feature-branch.md
+- 34-pull-request.md
+- 35-merge-pr.md
+- 36-merge-conflicts.md
 
 # Information for Learners
 learners: 

episodes/20-introduction.md

@@ -0,0 +1,21 @@
+---
+title: "Lesson 2: Code Style & Linting"
+teaching: 15
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## 
+
+## 

episodes/21-setup.md

@@ -0,0 +1,21 @@
+---
+title: "2.1 Setup"
+teaching: 10
+exercises: 2
+---
+
+## Setup
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+

episodes/22-example-code.md

@@ -0,0 +1,88 @@
+---
+title: "2.2 Some Example Code"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Obtaining Some Example Code
+
+Open a shell
+On own machine: open terminal with a bash shell
+Using the shell, we’re going to use Git to clone our example GitHub code repository
+The URL is bit long - see the session notes for a copy and pastable link - it’s the second link at the top
+git clone https://github.com/UNIVERSE-HPC/code-style-example
+
+
+## Examining the Code
+
+Next, let’s take a look at the code, which is in the root directory of the repository
+So the example code here is designed to process temperature data from a separate data file (which is also in the repository in the data directory)
+The idea is that is reads in fahrenheit data from a data file, and prints out fahrenheit temperatures in both celsius and kelvin
+The data file is a CSV file (see sc_climate_data_10.csv) which is held in the data directory
+It contains a number of lines, each containing a number of values, each separated by a comma
+There’s also a comment line at the top, to tell us what each column represents
+Now let’s take a look at the Python code
+Use any editor you like to open the file, I’ll use a command line one called nano
+If you’re on a Mac or Linux, you should be able to use this too
+cd code-style-example
+nano climate-analysis.py
+The code opens the data file, defines some functions to do some conversions 
+I should point out that the code is deliberately written to be bad
+In so many ways we’ll look into
+Developers sometimes talk about “code smells”
+Code smells are cursory indications from looking at the source code that a piece of code may have some deeper issues
+And looking at this code, it smells pretty terrible
+We can see that there is inconsistent spacing, bunching in some places, very spread out in others, for example
+This doesn’t engender a great deal of confidence that the code will work as we expect
+It raises the question that if the style of the code appears rushed, what else has been rushed?
+It’s design? Testing?
+Something to bear in mind when writing code!
+
+QUESTION: who has seen or used code that looks like this? Yes/No?
+QUESTION: who has written code like this? Yes/No
+
+No one writes great code that’s readable, well formatted, and well designed all the time
+Sometimes you often need to explore ideas with code to understand how the code should be designed
+May involve trying things out first
+But … the key is that once you understand how to do something,
+it’s a good idea to make sure it’s readable and understandable by others
+And this includes a future version of yourself, 6 months down the line
+So it’s really helpful to have good clean code so your colleagues or development team can understand it
+So it can be extended and otherwise modified in the future
+But it’s also a really good idea if you write readable code for just yourself.
+You never know. The code may be useful elsewhere!
+An all too familiar example is
+You stop developing a piece of code, and put it to one side. Maybe it’s not needed any more, perhaps a project has finished. You forget about it
+BUT… suddenly, there’s a need to use the code again
+Maybe all of it in another project, or maybe to just part of it
+You come back to your code, and it’s a mess you can’t understand
+By spending a little time now to write good code while you understand it,
+you can save yourself (and possibly others) a lot of time later
+
+## Running the Example Code
+
+Now despite the issues with the code, does it work? Let’s find out 
+So in the shell
+In the root directory of the repository, we can type
+python climate_analysis.py
+And we can see that the code does indeed appear to work, with celsius and kelvin values being printed to the terminal
+But how can we improve its code formatting?
+Let’s use Pylint, a static Python code analysis tool to help us
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::

episodes/23-analysing-code.md

@@ -0,0 +1,115 @@
+---
+title: "2.3 Analysing Code using a Linter"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Installing a Code Linter
+
+The first thing we need to do is Install pylint
+Now fortunately, pylint can be installed as a Python package
+QUESTION: who has installed a Python package before, using the program pip? Yes/No
+QUESTION: who has created and used a Python virtual environment before? Yes/No
+Ok, so we’re going to create what’s known as a virtual environment
+This is a genuinely very useful technique - I cannot recommend this strongly enough!
+There isn’t a developer I know that doesn’t use virtual environments to install their packages whenever they can
+And to be honest, this could be a topic all on its own
+The idea is that
+Instead of installing Python packages at the level of our machine’s Python installation, which we could do
+We’re going to install them within their own container, which is separate to the machine’s Python installation
+And then we’ll run our Python code only using packages within that virtual environment
+The benefit of this is that it creates a clear separation between the packages we use for this project, and the packages we use for another
+The other benefit is that we don’t end up with a machine’s Python installation with a clutter of a thousand different packages
+Can become very difficult to tell which packages are used for which project
+If someone else needs to run your code for example, by using a virtual environment, you can be sure what your code actually needs as dependencies
+
+## Setting up a Development Environment
+
+So let’s create a Python virtual environment now, and activate it
+So, make sure you’re in the root directory of the repository, then type
+python -m venv venv
+Here, we’re using the built-on Python venv module - short for virtual environment - to create a virtual environment directory called venv
+We could have called the directory anything, but naming it venv is a common convention
+We create the venv within the repository root directory, which is also an established convention
+This makes sure the venv is closely associated with this project, and not easily confused with another
+Once created, we can activate the venv so it’s the one in use
+We do that by:
+(if on Linux or Mac) source venv/bin/activate
+(if on Windows) source venv/Scripts/activate
+QUESTION: who has successfully created and activated their virtual environment? Yes/No?
+Ok, so what’s in this virtual environment?
+we can do: pip list
+We can see this is essentially empty, aside from some default packages that are always installed
+So, the next thing we can do is install any packages needed for this codebase
+It turns out, there isn’t any needed for the code itself
+But - we wish to use pylint, and that’s a python package
+So we can install pylint into our virtual environment using
+pip install pylint
+You’ll notice the prompt changes to reflect that the virtual environment is active - a handy reminder
+And with that, we’re ready to go
+Important thing with virtual environments
+Don’t add the venv directory to a GitHub repository
+
+## Analysing our Code using a Linter
+
+Now the magic can happen - let’s run pylint
+If you run it without any arguments, we can see it’s got a daunting array of options
+But fortunately the basic use is very simple
+Let’s point it at our code and see what it thinks
+pylint climate_analysis.py
+We run this, and it gives us a report
+essentially, a list of issues, and a score
+for each issue, it tells us the filename, the line number and text column the problem occurred, an issue identifier (what type of issue it is), and some text describing this type of error (as well as a shortened form of the error type)
+You’ll notice there’s also a score at the bottom, out of 10
+Essentially, for every infraction, it deducts from the ideal score of 10 
+It is perfectly possible to get a negative score! It just keeps deducting from 10!
+But we can see here that our score appears very low - 0.59/10
+If we were to resolve each of these issues in turn, we should get a perfect score
+We can also ask for more information on an error type
+for example, we can see at line 9, near column 35, there is a trailing whitespace
+pylint —help-msg C0303
+Which is helpful if we need clarification
+if we edit the file, e.g. nano climate-analysis.py
+and go to line 9, column 35,
+(we can use nano’s cursor locator function to help us find column 35),
+we can see that there is an unnecessary space
+I’ve made this visible in nano so you can see it (although usually you wouldn’t)
+QUESTION: who’s managed to run pylint on the example code? Yes/No
+Let’s fix this issue now. Let’s remove the space and re-run pylint on it
+Delete space, save
+pylint climate_analysis.py
+And we see that the error has disappeared and our score has gone up!
+Note that it also gives us a comparison against our last score
+Warning - it can get quite addictive to keep increasing your score
+which might well be the point!
+So looking at the issue types, what do the C, W, R symbols mean?
+Show pylint —long-help
+At the end, we can see a breakdown of what they mean
+I is for informational messages
+C for a programming standards violation - it’s not conforming to the normally accepted conventions of writing good code, things like variable or function naming
+R for a need to refactor, due to a “bad code smell”
+W for warning - something that
+E for error - so pylint think’s it’s spotted a bug (useful, but I wouldn’t depend on this!)
+and F for a fatal pylint error
+So if we run it again on our code
+pylint climate_analysis.py
+We can see that most of our issues are do to with conventions
+
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::

episodes/24-linter-advanced.md

@@ -0,0 +1,103 @@
+---
+title: "2.4 Advanced Linting Features"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## More Verbose Reporting
+
+We can also obtain a more verbose report, which gives us a lot more detail
+pylint —reports y file
+QUESTION: for those doing activity, who’s managed to run this command? YES/NO
+It gives  you some overall statistics, plus comparisons with the last time you ran it
+such as how many modules, classes, methods and functions were looked at
+some raw metrics - we’ll come back to that
+the extent of code duplication (none, which is good)
+the number of messages by category (again, we can see that it’s mainly convention issues)
+and a sorted count of the messages we received
+now coming back to the raw metrics
+We can see that  is breaks down our program into how many lines are
+code lines, 
+python docstrings
+standalone comments
+and empty lines
+this is very useful, since it gives us an idea of how well commented our code is
+in this case - not very well commented at all!
+what’s a good % of comments to aim for? well it depends
+for normal comments, the usually accepted wisdom is to add them to explain why you are doing something, or perhaps to explain how necessarily complex code works
+
+## Increasing our Pylint Score - Adding a Docstring
+
+QUESTION: Who’s familiar with Python docstrings? Yes/No
+for those that don’t know, docstrings are a special kind of comment for a function, that explain what the function does, the parameters it expects, and what is returned
+you can also write docstrings for classes, methods, and modules
+but you should usually aim to add docstring comments to your code wherever you can, particularly for critical or complex functions
+let’s add one to our code now, to the fahr_to_celsius function
+
+    """Convert fahrenheit to Celsius.
+
+    :param fahr: temperature in Fahrenheit
+    :returns: temperature in Celsius
+    """
+
+Re-run pylint - can see we have one less docstring error, and a slightly higher score
+If you’d like to know more about docstrings and commenting, we’ve included a link to a RealPython tutorial on comments and docstrings, and the different ways you can format them. that’s really good
+
+## Configuring Pylint Rules
+
+Specifying a pylint rcfile - e.g. to ignore/specify rules
+Write a module docstring that exceeds 100 characters
+Show pylint complaining about long line length
+pylint --generate-rcfile
+Specify long line length
+Edit .pylintrc file, add C0301 to disable=
+Re-run pylint
+When to use? Agree as a team
+
+## Summary
+
+What doesn’t pylint - and other code analysis tools - give us?
+What are their limitations?
+They don’t tell us that the code works - this first and foremost
+And they don’t tell us if the results our code produces are actually correct
+So we still need to test our code
+They don’t give us any Idea of whether it’s a good implementation
+And that the technical choices are good ones
+For example, this code does its own temperature conversions
+It turns out there’s a number of well-maintained Python packages that do this, e.g. pytemperature
+so we should be using a tried and tested package instead of reinventing the wheel
+They also don’t tell us if the implementation is actually fit for purpose
+Ok, so the code is a good implementation, and it works as expected
+But is it actually solving the intended problem?
+They also don’t tell us anything about the data the program may use
+Which may have its own problems
+So we have to be a bit careful
+These are all valid, high-level questions to ask while you’re writing code
+I’ve added them to the google doc
+As a team, and also individually
+In the fog of development, it can be surprisingly easy to lose track of what’s actually being implemented
+
+A good idea is to revisit these questions regularly, to be sure you can answer them!
+A high score or zero warnings may give us false confidence
+Just because we have reached a 10.00 score, doesn’t mean the code is actually GOOD
+Just that it’s likely well formatted and hopefully easier to read and understand
+But nevertheless, it’s a low effort way to check our code
+And such tools are still very useful, as far as they go
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::

episodes/30-introduction.md

@@ -0,0 +1,21 @@
+---
+title: "Lesson 3: Intermediate Git"
+teaching: 15
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## 
+
+##