Merge branch 'gh-pages' into bielsnohr/june-2024-ukaea-updates

README.md

@@ -1,3 +1,6 @@
+> [!NOTE]  
+> We are currently transitioning the lesson to the new Carpentries lesson format - please put your pull requests on hold and submit issues only.
+
 [![DOI](https://zenodo.org/badge/257930838.svg)](https://zenodo.org/badge/latestdoi/257930838)
 
 ## Intermediate Research Software Development Skills (Python)
@@ -53,7 +56,7 @@ label ![pilot](https://shields.io/badge/-pilot-31E930).
 We welcome all contributions to improve the lesson! Maintainers will do their best to help you if you have any
 questions, concerns, or experience any difficulties along the way.
 
-We'd like to ask you to familiarise yourself with our [Contribution Guide](CONTRIBUTING.md) and have a look at
+We would like to ask you to familiarise yourself with our [Contribution Guide](CONTRIBUTING.md) and have a look at
 the [more detailed guidelines][lesson-example] on proper formatting, instructions on compiling and rendering the lesson locally, and 
 making any changes and adding new content or episodes.
 

_episodes/00-setting-the-scene.md

@@ -25,8 +25,8 @@ So, you have gained basic software development skills either by self-learning or
 e.g., a [novice Software Carpentry course][swc-lessons].
 You have been applying those skills for a while by writing code to help with your work
 and you feel comfortable developing code and troubleshooting problems.
-However, your software has now reached a point where there’s too much code to be kept in one script.
-Perhaps it's involving more researchers (developers) and users,
+However, your software has now reached a point where there is too much code to be kept in one script.
+Perhaps it is involving more researchers (developers) and users,
 and more collaborative development effort is needed to add new functionality
 while ensuring previous development efforts remain functional and maintainable.
 

_episodes/10-section1-intro.md

@@ -20,7 +20,7 @@ and introducing the project that we will be working on throughout the course.
 In order to build working (research) software efficiently
 and to do it in collaboration with others rather than in isolation,
 you will have to get comfortable with using a number of different tools interchangeably
-as they’ll make your life a lot easier.
+as they will make your life a lot easier.
 There are many options when it comes to deciding
 which software development tools to use for your daily tasks -
 we will use a few of them in this course that we believe make a difference.
@@ -124,6 +124,6 @@ Therefore, one should be aware of these guidelines
 and adhere to whatever the project you are working on has specified.
 In Python, we will be looking at a convention called PEP8.
 
-Let's get started with setting up our software development environment!
+Let us get started with setting up our software development environment!
 
 {% include links.md %}

_episodes/11-software-project.md

@@ -251,7 +251,7 @@ A novice will often make up the structure of their code as they go along.
 However, for more advanced software development,
 we need to plan and design this structure - called a *software architecture* - beforehand.
 
-Let's have a quick look into what a software architecture is
+Let us have a quick look into what a software architecture is
 and which architecture is used by our software project
 before we start adding more code to it.
 

_episodes/12-virtual-environments.md

@@ -25,7 +25,7 @@ the `requirements.txt` file."
 ## Introduction
 So far we have cloned our software project from GitHub and inspected its contents and architecture a bit.
 We now want to run our code to see what it does -
-let's do that from the command line.
+let us do that from the command line.
 For the most part of the course we will run our code
 and interact with Git from the command line.
 While we will develop and debug our code using the PyCharm IDE
@@ -236,7 +236,7 @@ This will create the target directory for the virtual environment
 > and avoid issues that could prove difficult to trace and debug.
 {: .callout}
 
-For our project let's create a virtual environment called "venv".
+For our project let us create a virtual environment called "venv".
 First, ensure you are within the project root directory, then:
 
 ~~~
@@ -342,7 +342,7 @@ When you’re done working on your project, you can exit the environment with:
 ~~~
 {: .language-bash}
 
-If you've just done the `deactivate`,
+If you have just done the `deactivate`,
 ensure you reactivate the environment ready for the next part:
 
 ~~~
@@ -565,7 +565,13 @@ In the above command, we tell the command line two things:
 As we can see, the Python interpreter ran our script, which threw an error -
 `inflammation-analysis.py: error: the following arguments are required: infiles`.
 It looks like the script expects a list of input files to process,
-so this is expected behaviour since we don't supply any.
+so this is expected behaviour since we do not supply any.
 We will fix this error in a moment.
 
+## Optional exercises
+Checkout [this optional exercise]({{ site.baseurl }}{% link _episodes/17-section1-optional-exercises.md %}#exercise-try-out-different-virtual-environment-managers)
+to try out different virtual environment managers. 
+Or, [this exercise]({{ site.baseurl }}{% link _episodes/17-section1-optional-exercises.md %}#exercise-customize-the-command-line) 
+to customize the command line. 
+
 {% include links.md %}

_episodes/13-ides.md

@@ -80,10 +80,10 @@ and Microsoft's free [Visual Studio Code (VS Code)](https://code.visualstudio.co
 
 ## Using the PyCharm IDE
 
-Let's open our project in PyCharm now and familiarise ourselves with some commonly used features.
+Let us open our project in PyCharm now and familiarise ourselves with some commonly used features.
 
 ### Opening a Software Project
-If you don't have PyCharm running yet, start it up now.
+If you do not have PyCharm running yet, start it up now.
 You can skip the initial configuration steps which just go through
 selecting a theme and other aspects.
 You should be presented with a dialog box that asks you what you want to do,
@@ -156,7 +156,7 @@ and PyCharm is clever enough to understand it.
    so we can also use this environment for other projects if we wish.
 6. Select `OK` in the `Add Python Interpreter` window.
    Back in the `Preferences` window, you should select "Python 3.11 (python-intermediate-inflammation)"
-   or similar (that you've just added) from the `Project Interpreter` drop-down list.
+   or similar (that you have just added) from the `Project Interpreter` drop-down list.
 
 Note that a number of external libraries have magically appeared under the
 "Python 3.11 (python-intermediate-inflammation)" interpreter,
@@ -170,7 +170,7 @@ and has added these libraries effectively replicating our virtual environment in
 Also note that, although the names are not the same -
 this is one and the same virtual environment
 and changes done to it in PyCharm will propagate to the command line and vice versa.
-Let's see this in action through the following exercise.
+Let us see this in action through the following exercise.
 
 > ## Exercise: Compare External Libraries in the Command Line and PyCharm
 > Can you recall two places where information about our project's dependencies
@@ -314,15 +314,15 @@ You can also verify this from the command line by
 listing the `venv/lib/python3.11/site-packages` subdirectory.
 Note, however, that `requirements.txt` is not updated -
 as we mentioned earlier this is something you have to do manually.
-Let's do this as an exercise.
+Let us do this as an exercise.
 
 > ## Exercise: Update `requirements.txt` After Adding a New Dependency
 > Export the newly updated virtual environment into `requirements.txt` file.
 >
 >  
 >> ## Solution
->> Let's verify first that the newly installed library `pytest` is appearing in our virtual environment
->> but not in `requirements.txt`. First, let's check the list of installed packages:
+>> Let us verify first that the newly installed library `pytest` is appearing in our virtual environment
+>> but not in `requirements.txt`. First, let us check the list of installed packages:
 >> ~~~
 >> (venv) $ python3 -m pip list
 >> ~~~
@@ -412,7 +412,7 @@ and use on top of virtual environments.
    (i.e. the virtual environment and interpreter you configured earlier in this episode)
    in the `Python interpreter` field.
 5. You can give this run configuration a name at the top of the window if you like -
-   e.g. let's name it `inflammation analysis`.
+   e.g. let us name it `inflammation analysis`.
 6. You can optionally configure run parameters and environment variables in the same window -
    we do not need this at the moment.
 7. Select `Apply` to confirm these settings.
@@ -438,15 +438,15 @@ and use on top of virtual environments.
 Now you know how to configure and manipulate your environment in both tools
 (command line and PyCharm),
 which is a useful parallel to be aware of.
-Let's have a look at some other features afforded to us by PyCharm.
+Let us have a look at some other features afforded to us by PyCharm.
 
 ### Syntax Highlighting
 The first thing you may notice is that code is displayed using different colours.
 Syntax highlighting is a feature that displays source code terms
 in different colours and fonts according to the syntax category the highlighted term belongs to.
 It also makes syntax errors visually distinct.
 Highlighting does not affect the meaning of the code itself -
-it's intended only for humans to make reading code and finding errors easier.
+it is intended only for humans to make reading code and finding errors easier.
 
 ![Syntax Highlighting Functionality in PyCharm](../fig/pycharm-syntax-highlighting.png){: .image-with-shadow width="1000px" }
 
@@ -569,7 +569,12 @@ We will get back to this error shortly -
 for now, the good thing is that we managed to set up our project for development
 both from the command line and PyCharm and are getting the same outputs.
 Before we move on to fixing errors and writing more code,
-let's have a look at the last set of tools for collaborative code development
+Let us have a look at the last set of tools for collaborative code development
 which we will be using in this course - Git and GitHub.
 
+
+## Optional exercises
+Checkout [this optional exercise]({{ site.baseurl }}{% link _episodes/17-section1-optional-exercises.md %}#exercise-try-out-different-integrated-development-environments)
+to try out different IDEs and code editors.
+
 {% include links.md %}

_episodes/14-collaboration-using-git.md

@@ -36,7 +36,7 @@ test it to make sure it works correctly and as expected,
 then record your changes using version control
 and share your work with others via a shared and centrally backed-up repository.
 
-Firstly, let's remind ourselves how to work with Git from the command line.
+Firstly, let us remind ourselves how to work with Git from the command line.
 
 ## Git Refresher
 Git is a version control system for tracking changes in computer files
@@ -57,9 +57,8 @@ Git has several important characteristics:
   so even if you make a mistake you can revert to a point before it.
 
 The diagram below shows a typical software development lifecycle with Git
-(starting from making changes locally) and the commonly used commands to interact
-with different parts of the Git infrastructure,
-such as:
+(in our case starting from making changes in a local branch that "tracks" a remote branch) and the commonly used commands to interact
+with different parts of the Git infrastructure, including:
 - **working directory** -
   a local directory (including any subdirectories) where your project files live
   and where you are currently working.
@@ -102,24 +101,23 @@ such as:
 Created with https://mermaid.live/edit#pako:eNqVkjFrwzAQhf-KuKmlKd01BAoZ2yUZumi5SmdbRPI58oliQv57JbuloSaFajqd3sd7x-kMlh2BhpFOmXpLO49twmh6Vc4bp6PvW7Xziaxwmh6324eDYFubz4lQq9aLQucW_fVTlb6wxaD2NPDoK77ILcfoZSF-Kyq1p8hCK2zIY7dAK8Ftr4bEdretVgPqOWBH9shZ_stFSi39EXFNfQ0WgrobO05ic4nM6Sd6uYXAH-TU-6Susz3NZvewgVJE9K7s8Fy9DUhHkQzoUjpqMAcxYPpLkWIWPky9BS0p0wby4FC-Vw66wTCWLrma-HX5F_P3uHwCS-vA3Q
 sequenceDiagram
     Working Directory->>+Staging Area: git add
-    Staging Area->>+Local Repository: git commit
-    Local Repository->>+Remote Repository: git push
-    Remote Repository->>+Local Repository: git fetch
-    Local Repository->>+Working Directory:git checkout
-    Local Repository->>+Working Directory:git merge
-    Remote Repository->>+Working Directory: git pull (shortcut for git fetch followed by git checkout/merge)
+    Staging Area->>+Local Repository Branch: git commit
+    Local Repository Branch->>+Remote Repository Branch: git push
+    Remote Repository Branch->>+Local Repository Branch: git fetch
+    Local Repository Branch->>+Working Directory:git merge
+    Remote Repository Branch->>+Working Directory: git pull (shortcut for git fetch followed by git merge for a 'tracking branch')
 -->
 <!--
 SVG of the diagram can be downloaded from:
-[![](https://mermaid.ink/img/pako:eNqVUj1PwzAQ_SvWTSCK2D1UQuoISzuwZDnsi2PVzgXnLBRV_e_YiSoKUZHwdL57T-_dxwkMWwINI31k6g3tPLqEselVeW-cjr53aucTGeE0PW63DwdBV5PPiVAr50WhtQv-ulShL2wwqD0NPPpKX-CGY_SyMH4jKmtPkYVWtCGP3UJaAW5rtSSmuy31o5fZW0fmyFn-QYmUHP1hbDXESzshqLux4yQmF6Ocvg2XXwj8SVa9T-ra1tMsdg8bKEFEb8vmTlW7AekoUgO6hJZazEEaaPpzgWIWPky9AS0p0wbyYFEuiwbdYhhLlmx1_Lpcw3wU5y-9M7w9?type=png)](https://mermaid.live/edit#pako:eNqVUj1PwzAQ_SvWTSCK2D1UQuoISzuwZDnsi2PVzgXnLBRV_e_YiSoKUZHwdL57T-_dxwkMWwINI31k6g3tPLqEselVeW-cjr53aucTGeE0PW63DwdBV5PPiVAr50WhtQv-ulShL2wwqD0NPPpKX-CGY_SyMH4jKmtPkYVWtCGP3UJaAW5rtSSmuy31o5fZW0fmyFn-QYmUHP1hbDXESzshqLux4yQmF6Ocvg2XXwj8SVa9T-ra1tMsdg8bKEFEb8vmTlW7AekoUgO6hJZazEEaaPpzgWIWPky9AS0p0wbyYFEuiwbdYhhLlmx1_Lpcw3wU5y-9M7w9)
+https://mermaid.ink/svg/pako:eNqFksFuwyAMhl8FcemmdS_AodKm7rZe2sOkKRcXnAQNcEaMpqjquw-SZZtUReEE9vfbP5iL1GRQKtnjZ8KgcW-hieCrIPJ6o_hhQyP2NqJmisPjbvdwYmhK8CkiKNFYFmDMxP9PFfSVNDhxxI56W-TiOULQ7aTS5L3lSbgAlhpH9MS4VKRLfTuVWOJWfdTIul21cfMUqmg9xgbX-9-Kf8w7J-76liLrlI1Q_DOUT87RFxpxHsRvq5EBseEIeqx4Hnts7uVWZsCDNXmWl-Koktyix0qqvDVYQ3JcySpcMwqJ6TQELRXHhFuZOgM8j16qGlyfo2jKPQ7T_xi_yUy-jJlZ3UF4J5p112_HVM9r
 -->
-![Development lifecycle with Git, containing Git commands add, commit, push, fetch, checkout, merge and pull](../fig/git-lifecycle.svg){: .image-with-shadow width="600px"}
+![Development lifecycle with Git, containing Git commands add, commit, push, fetch, restore, merge and pull](../fig/git-lifecycle.svg){: .image-with-shadow width="600px"}
 <p style="text-align: center;">
 Software development lifecycle with Git
 </p>
 
 ## Checking-in Changes to Our Project
-Let's check-in the changes we have done to our project so far.
+Let us check-in the changes we have done to our project so far.
 The first thing to do upon navigating into our software project's directory root
 is to check the current status of our local working directory and repository.
 
@@ -164,7 +162,7 @@ and stop notifying us about it.
 Edit your `.gitignore` file in PyCharm
 and add a line containing "venv/" and another one containing ".venv/".
 It does not matter much in this case where within the file you add these lines,
-so let's do it at the end.
+so let us do it at the end.
 Your `.gitignore` should look something like this:
 
 ~~~
@@ -258,7 +256,7 @@ $ git pull
 ~~~
 {: .language-bash}
 
-Now we've ensured our repository is synchronised with the remote one,
+Now we have ensured our repository is synchronised with the remote one,
 we can now push our changes:
 
 ~~~
@@ -326,11 +324,11 @@ $ git branch
 ~~~
 {: .output}
 
-At the moment, there's only one branch (`main`)
+At the moment, there is only one branch (`main`)
 and hence only one version of the code available.
 When you create a Git repository for the first time,
 by default you only get one version (i.e. branch) - `main`.
-Let's have a look at why having different branches might be useful.
+Let us have a look at why having different branches might be useful.
 
 ### Feature Branch Software Development Workflow
 While it is technically OK to commit your changes directly to `main` branch,
@@ -343,7 +341,7 @@ Each feature branch should have its own meaningful name -
 indicating its purpose (e.g. "issue23-fix").
 If we keep making changes and pushing them directly to `main` branch on GitHub,
 then anyone who downloads our software from there will get all of our work in progress -
-whether or not it's ready to use!
+whether or not it is ready to use!
 So, working on a separate branch for each feature you are adding is good for several reasons:
 
 * it enables the main branch to remain stable
@@ -384,7 +382,7 @@ Whichever is the case for you, a good rule of thumb is -
 nothing that is broken should be in `main`.
 
 ### Creating Branches
-Let's create a `develop` branch to work on:
+Let us create a `develop` branch to work on:
 
 ~~~
 $ git branch develop
@@ -437,7 +435,7 @@ the commits will happen on the `develop` branch
 and will not affect the version of the code in `main`.
 We add and commit things to `develop` branch in the same way as we do to `main`.
 
-Let's make a small modification to `inflammation/models.py` in PyCharm,
+Let us make a small modification to `inflammation/models.py` in PyCharm,
 and, say, change the spelling of "2d" to "2D" in docstrings for functions
 `daily_mean()`,
 `daily_max()` and
@@ -507,7 +505,7 @@ $ git push -u origin develop
 > We still prefer to explicitly state this information in commands.
 {: .callout}
 
-Let's confirm that the new branch `develop` now exist remotely on GitHub too.
+Let us confirm that the new branch `develop` now exist remotely on GitHub too.
 From the `Code` tab in your repository in GitHub,
 click the branch dropdown menu (currently showing the default branch `main`).
 You should see your `develop` branch in the list too. 
@@ -528,7 +526,7 @@ $ git push origin develop
 {: .language-bash}
 
 > ## What is the Relationship Between Originating and New Branches?
-> It's natural to think that new branches have a parent/child relationship
+> it is natural to think that new branches have a parent/child relationship
 > with their originating branch,
 > but in actual Git terms, branches themselves do not have parents
 > but single commits do.