Locating course resources

How to obtain the latest version of this resource:

1. visit the accompanying website csci-1301.github.io. This website includes the latest version of the course textbook in all supported formats, links to labs, and all other available student resources.
2. AU-hosted mirror of the website is located at https://spots.augusta.edu/caubert/teaching/csci-1301
3. latest version of built resource is available as a .zip file under releases on Github.

A mirrored version of this website is hosted on spots and updated regularly. Additional copies of this resource can be made available through box or D2L. Because manual effort is required to share the resource through these channels, these may be slightly behind the latest version.

How to obtain much earlier versions of this resource:

1. Complete release history is accessible under releases on Github
2. Earlier versions of this resource will be periodically archived on Galileo.

Best practices for all forms of content

!["image of visual studio IDE"](./img/vs_ide.jpg){ width=80% }

Creating new lectures

All lecture notes are under lectures directory. This directory also contains an index indicating the related labs and prerequisites for each lecture.

To create a new lecture, e.g. lecture xyz:

1. Create a directory called NNN_lecture_xyz under lectures directory

   • Follow the existing pattern for naming convention which is lowercase and separation by underscores.
   • The numbers NNN tell pandoc how to order book content. Use leading zero and increments of 10.
   • Choose this number based on where in the book the new lecture should appear.

2. under the new directory, create a file readme.md (lowercase). Write lecture notes in this file using markdown.

   • We use filename readme.md because the build script looks for files matching this pattern.

Following these steps will automatically include the new lecture in the book.

If the lecture does not appear, here are the steps for troubleshooting the issue:

1. Check that after committing changes, the automated build has completed successfully
2. The newly created lecture is immediately under lectures/ directory
3. The readme.md exists
4. In gh-pages branch, ensure the book is generated
5. Hard refresh the browser page if viewing the resources website

Do not include meta section in individual lecture files because these lectures will be concatenated by pandoc into a single larger document. Any meta data in individual files would appear somewhere in the middle of the larger document, and as such will not be treated as front matter.

Known issues: When concatenating files pandoc may or may not include empty spaces between individual files. This may cause the subsequent lecture title to not appear in the generated book. For this reason, each lecture file should end with a newline.

Creating new labs

All lab resources are located under labs directory. At build time these labs are compiled into instructions in various document formats with an optional, accompanying source code solution.

1. Choose a short and unique name that describes the lab then create a directory matching that name

   • follow the existing convention for naming
   • do not number labs or make assumptions about numbering because another instructor may not follow the exact same lab order

2. Under the lab directory create:

   1. readme.md (case sensitive)
      • write lab instructions in this file. You should include meta data, at minimum a title
      • make the lab standalone to support alternative ordering (avoid assumptions about what was done “last time”)
      • do not make assumptions about student using specific OS, include instructions for all supported options (Windows, MacOS, Linux)
      • do not make assumptions about student using Visual Studio, refer to IDE instead
   2. (optional) if you want to include starter code with the lab,
      • create a subdirectory called src
      • create a subdirectory with the name of the solution you would like to use,
      • create a subdirectory with the name of the project you would like to use,
      • create a file called Program.cs in src/<solution>/<project>/Program.cs
      • if you want to add additional classes, add them in src/<solution>/<project>/<Class>.cs files.

   Do not add solution (sln) or project (csproj) files: they will be created automatically using the project and solution’s name you specified, if multiple classes are present they will all be linked, and the resulting archive will be hosted in the lab’s folder as <solution>.zip.

   Note / known issue: when including multiple solutions, the basename should be different, for example: SomeLab and Solution_SomeLab (instead of SomeLabSolution); to ensure solutions are packaged separately from one another.

   1. Create an entry for the new lab in the table at labs/readme.md. List all prerequisite labs and related lectures.

If you follow these instructions the lab will be automatically built into a distributable format when you commit changes. It works as follows:

1. readme.md will be converted to lab instructions file called index (html, pdf, odt)
2. contents of src will be converted to a standalone C# solution as a zip file.

Using this established build system generates labs that are cross-platform (Windows, MacOS, Linux) and work on different IDEs. Do not attempt to create labs locally as that approach does not have the same cross-platform guarantee.

Labelling with shortcodes

Use emoji shortcodes to label following course resources

Labelling using text labels

1. Each resource will be labelled with prerequisites.

   This is a list of zero or more values. For zero prerequisites write None. These requirements are expressed in the associated index of lectures/labs/problems (cf. lectures).

2. Lecture notes and slides will be labelled by related labs, and vice versa

   These requirements are expressed in the associated index of lectures and labs (cf. lectures).

Updating docx template

First, output the default template file:

{bash} pandoc -o custom-reference.docx --print-default-data-file reference.docx

Then, open reference.docx, and, following loosely this tutorial, do:

• Click pretty much anywhere, and right-click on the highlighted style (displayed if you are under “Home”, you may need to scroll down the styles),
• Change the font for everything but the source code,
• Click on the “Block code”, then right-click on the highlighted style, and select the font for the source code,
• The font for “Verbatim Char” was also changed, but I am not sure if this has an impact,
• Make sure the fonts are embedded,
• Save and close the document.

This was inspired by this post but does not seem to work properly :-/

Updating odt template

First, output the default template file:

{bash} pandoc -o custom-reference.odt --print-default-data-file reference.odt

Then, open reference.odt, and, following loosely this tutorial, do:

• View -> Styles
• Right-click on “Preformatted Text”, click on “Modify…”, and then select the desired font family for source code.
• In the dialog or sidebar which opens make sure the button in the top panel marked with ¶ is highlighted (it is very subtle).
• In the menu at the bottom of the dialog/sidebar choose Applied Styles. Only “Default Paragraph Style” and “Footer” should appear.
• Right-click on “Default Paragraph Style”, click on “Modify…”, and then select the desired font family for the rest of the text.
• Then, highlight the A next to ¶.
• Right-click on “Source_Text”, click on “Modify…”, and then select the desired font family for source code.
• File -> Properties -> Font tab, click on “Embed fonts in the document”.
• Save and close the document.

How build outputs are generated

The resource material is organized into specific directories (cf. resource organization). These resources are then compiled into templated documents in various formats using pandoc. Different directories undergo different build steps as defined in the project Makefile and generate various outputs. For example, lecture notes are compiled into a textbook and labs are packaged into individual labs. The makefile explains the exact steps applied to each type of resource.

Using Github actions with pandoc

This resource is built automatically every time changes are committed to the main branch of the repository. This is configured to run on Github actions. There are currently two configured workflows: one to build the resource and to deploy it, and a second one to check that any opened pull requests can be built successfully.

The build configuration uses texlive to keep the dependency installation time low. Similarly, the choice of Python packages is preferable for pandoc filters, because they are usually straightforward and fast to install. We want to avoid choosing packages that significantly increase build time.

Currently Github actions offers unlimited free build minutes for public repositories (and 2000 min/mo. for private repositories, should we ever need them), which hopefully continues in perpetuity (if it does not there are other alternative services). Going with one specific CI service over another is simply a matter of preference.

Following a successful build, the build script will automatically deploy the generated resources to an accompanying website hosted on github pages. In the repository a special branch gh-pages represents the contents of the deployed website. It also allows maintainers to observe the generated build outputs.

How to create releases

Currently a github action is setup to do the following: whenever a new commit is made to the main branch, the action will build the resource and add the generated books as a pre-release under releases and tag them as “latest”. If a subsequent commit occurs it will overwrite the previous latest files and become the new latest version. This cycle continues until maintainers are ready to make a versioned release (or “package”).

Making a versioned release is done as follows:

1. Go to repository releases
2. Choose latest, which contains the files of the latest build
3. Edit this release, giving it a semantic name and a version, such as v1.0.0. Name and version can be the same. (cf. semantic versioning)
4. Enter release notes to explain what changed since last release
5. Uncheck “This is a pre-release”
6. Check “Set as the latest release”
7. Update release

Following these steps will generate a new, versioned release. The versioned releases will be manually uploaded to and archived on galileo.

Once this is done, remember to create the next pre-release:

1. Go to the repository releases.
2. Click on “Draft a new release”.
3. Pick the tag “Latest”.
4. Click on “Generate release notes”
5. Check “This is a pre-release”
6. Click on “Publish release”

Building the resource locally

It is generally not necessary to build this resource locally unless the intent is to preview templating changes or to make changes to build scripts. For the purposes of editing content, it is sufficient to make edits to markdown files and commit those changes.

pip install -U panflute

make

make help

Maintaining repository feedback

Resource users can submit feedback about the resource through various means, one of which is leaving comments on the website. This feature is enabled by utteranc.es.

To manage user feedback over time, a semester-specific repository is created for issues only. This must be a public repository and located under the same organization as the resources repository. utteranc.es widget is configured to point to this repository. After a semester is over, this feedback repository will be archived, and a new one created for the next semester. This will simultaneously archive all older issues and reset the feedback across website pages.

Maintaining Instructors / G/UCA rights

Every semester,

• The members of the “UCAs” team should be updated,
• A “uca-resources--YYYY” repository should be created, by forking the template (private repository),
• The new repository should be added to the list of repositories of the team (as maintainer),
• The old repository should be deleted from that same list, and then archived.
• GRAs should be added / removed from the instructors list, and previous instructors should be removed from that same list,
• GRAs should be added to the “UCAs” teams and given “maintainer” rights (inside that team, and not for the whole organization).