Migrate the SEAMS site from GitLab

.gitattributes

@@ -0,0 +1,5 @@
+###############################################################################
+# Set default behavior to automatically normalize line endings.
+###############################################################################
+* text=auto
+

.github/workflows/pages.yml

@@ -0,0 +1,56 @@
+# Build the Jekyll site (github-pages gem) and deploy it to GitHub Pages.
+# Ported from the original GitLab CI (`bundle exec jekyll build`). Pull requests
+# build the site to validate it; only pushes to main deploy.
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; do not cancel an in-progress production run.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.1"
+          bundler-cache: true
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    # Build validates on PRs; deploy only from main / manual dispatch.
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

00_principles.md

@@ -0,0 +1,25 @@
+---
+layout: page
+title: Principles
+permalink: /principles/
+---
+# Focus Topics
+
+The *Principles* course covers five focuses in five days. Those Focuses are:
+
+ - Project Planning & Design
+ - Workspace Organization & Tools
+ - Reuse & Reusability
+ - IO, Big and small
+ - High Performance Computing
+
+# Schedule
+
+Each day adopts a different lens on **your work**, and follows the same schedule:
+
+ - warming up,
+ - opening with a faculty-led *focus discussion* on core concepts,
+ - transitioning to a *applied practical* where participants work a structured problem, and
+ - culminating in *project work* devoted to tasks and feedback on **your project**.
+
+The mornings start with [Warmups]({{ '/warmup/' | relative_url }}) followed by the [Focus Topics]({{ '/topic/' | relative_url }}), where the faculty engage participants in the important ideas & practices in the day's topic; these sessions are very interactive, and include several partnered mini-exercises.  In the afternoon, we shift to working more with the keyboard.  First, we complete a [Practical]({{ '/practical/' | relative_url }}) example problem tailored to the day's topic.  Lastly, the participants close out each day working through a series of [project tasks]({{ '/project/' | relative_url }}) applied to *their own projects*; the faculty prepare these challenge lists to exceed what can be accomplished in the available time, so participants will be able to choose what aspects of their work they want pursue in greater depth.

01_workshop.md

@@ -0,0 +1,8 @@
+---
+layout: page
+title: Workshop
+permalink: /workshop/
+---
+Our *SEAMS Workshop* extends the [Principles]({{ '/principles/' | relative_url }}) course to include a hack-a-thon during the second week.  The topic focus and schedule for the first week remains largely the same, though we integrate development of a work plan for the hack-a-thon.
+
+During the hack-a-thon week, the schedule is more flexible. Participants meet with faculty on a regularly scheduled basis to check-in on how their plan is progressing, but *they set that plan*. The workshop wraps with participants demonstrating changes to their project's engineering.

02_schedule.md

@@ -0,0 +1,39 @@
+---
+layout: page
+title: Schedule
+permalink: /schedule/
+---
+
+{:.schedule-table}
+|             Design             |             Workspace             |             Reuse             |             IO             |             HPC             |
+|:------------------------------:|:---------------------------------:|:-----------------------------:|:--------------------------:|:---------------------------:|
+| [Discussion]({{ '/session/design' | relative_url }})  | [Discussion]({{ '/session/workspace' | relative_url }})  | [Discussion]({{ '/session/reuse' | relative_url }})  | [Discussion]({{ '/session/io' | relative_url }})  | [Discussion]({{ '/session/hpc' | relative_url }})  |
+| [Practical]({{ '/practical/design' | relative_url }}) | [Practical]({{ '/practical/workspace' | relative_url }}) | [Practical]({{ '/practical/reuse' | relative_url }}) | [Practical]({{ '/practical/io' | relative_url }}) | [Practical]({{ '/practical/hpc' | relative_url }}) |
+|   [Project]({{ '/project/design' | relative_url }})   |   [Project]({{ '/project/workspace' | relative_url }})   |   [Project]({{ '/project/reuse' | relative_url }})   |   [Project]({{ '/project/io' | relative_url }})   |   [Project]({{ '/project/hpc' | relative_url }})   |
+|   [Reference]({{ '/topic/design' | relative_url }})   |   [Reference]({{ '/topic/workspace' | relative_url }})   |   [Reference]({{ '/topic/reuse' | relative_url }})   |   [Reference]({{ '/topic/io' | relative_url }})   |   [Reference]({{ '/topic/hpc' | relative_url }})   |
+
+The schedule for SEAMS is divided into two weeks; only the first week applies for the *Principles* course.
+
+Week 1 concerns our five topic focuses (more below), with each day comprising:
+ - Warmup, roughly 0830-0930: a quick exercise to get participants thinking
+ - Topic Discussion, roughly 0930-1230 with a half hour tea break: interactive discussion of the day's focus.
+ - Lunch, 1230-1330
+ - Practical, 1330-1500: a guided practical exercise for the day's topic
+ - Afternoon tea, 1500-1530
+ - Personal Project Work, 1530-1730: participants apply the set of questions from the day's topic to their personal projects
+
+Optional Weekend group activity: Table Mountain Hike, Saturday morning, approximately 9 AM start (to avoid heat) from Kirstenbosch side.
+
+Week 2 concerns coached personal project work. At the end of week 1, participants will develop a plan for week 2.
+ - Monday-Thursday: schedule on an individual basis. Every day will have a scheduled chat with one of the faculty (rotating among them) in the morning and afternoon.
+ - Friday morning: participants will present their project work to the group
+
+## Topic Focuses
+
+We focus on five topic areas:
+
+ - Project Organization: What is required to accomplish your project? What are the pieces that you'll use? How should you arrange them? How will they work together? How can those choices help (or hinder!) you plan to get work done?
+ - Workspace Tools: What tools should you use? Are there some you have to use? How do they help you work with collaborators? Do they demand too much for those collaborators? Do they comply with your project requirements, like data privacy?
+ - Reuse & Reusability: Are there parts of your project that someone else (maybe even your past self!) has already implemented? Are there parts that someone else (hopefully, future you!) will want to use? What should you do to make your code more friendly to including other work, and being included elsewhere?
+ - Input & Output: What kind of data do you have? How much do you have? What format should you support reading in? Storing output in? What lines in your code currently should be input instead?
+ - High Performance Computing: Where is your project stumbling? Too much data, inefficient implementations? If everything is highly tuned, and it's still too much for your personal machine, what next? How you can break up your problem in bits that will work in parallel? How you can write code that will be cluster-computation ready?

99_communications.md

@@ -0,0 +1,19 @@
+---
+layout: page
+title: Contact Us!
+permalink: /communications/
+---
+
+Email us at: [seams@aims.ac.za](mailto:{{ site.email }}), or contact us via {% include icon-twitter.html username=site.twitter_username -%}!
+
+The repository for the course materials is {% include icon-gitlab.html username=site.gitlab_username -%}, where we happily accept accept issues. For updating personal information, we expect workshop alums will also include a pull request.  For problems with the site, just a thorough description of the error is enough.
+
+## Publications
+
+Past participants: have a publication you want us to recognize (particularly those derived from project work at SEAMS)?  Just let us know via [email](mailto:seams@aims.ac.za) or [@SeamsWorkshop](https://twitter.com/SeamsWorkshop)!  We will add to the site, distribute to other alumni, *et cetera*.
+
+## Acknowledgement Statement
+
+If you think that one of your future publications was substantially influenced by your participation in the SEAMS Workshop, we would appreciate you acknowledging the workshop.  We suggest working from the following phrasing, with additional specifics as appropriate:
+
+> We thank the Software Engineering for Applied Mathematical Sciences (SEAMS) Workshop (link or citation as appropriate) participants and faculty, YEAR and LOCATION, for valuable feedback on early versions of the code underlying this work. In particular, (...description of the major software engineering insights and how they improved the product).

Gemfile

@@ -0,0 +1,15 @@
+source "https://rubygems.org"
+
+# This will help ensure the proper Jekyll version is running.
+# gem "jekyll", "~> 4.3.3"
+
+gem "github-pages", '~> 232' #, group: :jekyll_plugins
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
+  gem "tzinfo", "~> 1.2"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?

Makefile

@@ -0,0 +1,83 @@
+## some convenience methods
+
+run:
+	bundle exec jekyll serve -w --config=_config.yml,_locconfig.yml
+
+PROFB ?= master
+
+profile:
+	git remote add $(TAR) git@gitlab.com:$(TAR)/seams-workshop.gitlab.io
+	git fetch $(TAR)
+	git checkout -b $(TAR)/$(PROFB)
+
+MOVES = $(wildcard _participants/*.md)
+
+moves2018: $(subst .md,.yml,$(subst _participants,_data/dec2018,$(MOVES)))
+
+_data/dec2018/%.yml:
+	git mv _participants/$*.md $@ || mv _participants/$*.md $@
+
+Vertical_Signature_Blue.eps:
+	rm -f $@
+	curl -o temp.zip "http://identity.ufl.edu/wp-content/uploads/2015/11/Vertical_Signature_Blue.eps_.zip"
+	unzip temp.zip
+	rm temp.zip
+
+%.pdf: %.eps
+	epstopdf $^
+
+_includes/logo-UF.svg: Vertical_Signature_Blue.pdf
+	pdf2svg $^ $@
+
+## TODO make target for favicon generation
+## found via https://stackoverflow.com/questions/48956465/favicon-standard-2018-svg-ico-png-and-dimensions
+## This site seems to do the works, web service API: https://realfavicongenerator.net/api/non_interactive_api#.W1CMltgzbOQ
+## looks like need to send SVG + a config.json via POST to site
+## then put the results in the right places locally
+
+RFG := https://realfavicongenerator.net/api/favicon
+RFGKEYPATH := ~/Google\ Drive/SEAMS/rfgkey.mk
+## TO USE THIS TARGET, MUST DEFINE THIS MAKEFILE LOCALLY, WITH RFGKEY := ... IN IT
+-include $(RFGKEYPATH)
+
+myrfg.json: rfg.json
+	## TODO stop unless RFGKEY is something?
+	sed -e 's/REPLACEME/$(RFGKEY)/g' $^ > $@
+
+favicons.zip: myrfg.json
+	curl -H "Content-Type: application/json" --data @$^ $(RFG) > tmp.json
+	grep -Eo '"package_url":.*?[^\\]",' tmp.json | sed -e 's/"package_url": "//' | sed -e 's/",//' | sed -e 's/\\//g' > tmp.url
+	cat tmp.url | xargs curl -o $@ -O
+	rm tmp.json
+	rm tmp.url
+
+_includes/html_code.html: favicons.zip
+	unzip $^
+	mv $(subst _includes/,,$@) $@
+
+.PHONY: gbranches
+
+define brancher
+git checkout -B $1-$2
+git push --set-upstream origin $1-$2
+
+endef
+
+gbranches:
+	$(foreach sess,reference practical project discussion,$(foreach top,design workspace reuse io hpc,$(call brancher,$(sess),$(top))))
+
+PROJECTAPIURL = https://gitlab.com/api/v4/projects/7337508
+
+define mrequestor # usage $(call mrequestor,$sess-$top,...)
+COUNTBRANCHES=`curl --silent "${PROJECTAPIURL}/merge_requests?state=opened" --header "PRIVATE-TOKEN:${gitlabapi}" | grep -o "\"source_branch\":\"$1\"" | wc -l`; if [ $$COUNTBRANCHES -eq "0" ]; then \
+	cp mergerequest.json $1.tmp; \
+	sed -e 's/REPLACEME/$1/g' $1.tmp > $1.json; \
+	rm $1.tmp; \
+	curl -X POST "${PROJECTAPIURL}/merge_requests" --header "PRIVATE-TOKEN:${gitlabapi}" --header "Content-Type: application/json" --data @$1.json; \
+fi
+# create the correct merge request json
+
+endef
+
+gmrs:
+	$(foreach sess,reference practical project discussion,$(foreach top,design workspace reuse io hpc,$(call mrequestor,$(sess)-$(top))))

README.md

@@ -0,0 +1,91 @@
+# SEAMS
+
+Site for the **Software Engineering for Applied Mathematical Sciences (SEAMS)**
+workshop, an ICI3D clinic. Jekyll site (built with the `github-pages` gem),
+deployed to GitHub Pages at <https://ici3d.github.io/SEAMS/>.
+
+Migrated from GitLab (`gitlab.com/SEAMS-Workshop/seams-workshop.gitlab.io`) into
+ICI3D; see ICI3D/SEAMS#1. Theme and schedule-workflow integration are tracked
+against ICI3D/ICI3D.github.io#56 / #54.
+
+## Using Jekyll locally
+
+From the repository root:
+
+1. [Install Jekyll](https://jekyllrb.com/docs/installation/).
+1. Download dependencies: `bundle install`
+1. Build and preview: `bundle exec jekyll serve`
+1. Open <http://localhost:4000/SEAMS/>.
+
+## Deployment
+
+`.github/workflows/pages.yml` builds the site on every push and pull request;
+pushes to `main` also deploy it to <https://ici3d.github.io/SEAMS/>. Pull
+requests build only, to validate.
+
+The base path is set in `_config.yml` (`baseurl: /SEAMS`), and internal links use
+the `relative_url` filter, so a future custom domain serving the site at the root
+just needs `baseurl: ""`.
+
+## Editing
+
+Work in small chunks, one topic at a time: branch (or fork) the repo, make the
+edit, open a pull request, and a maintainer reviews and merges. You can edit
+directly in GitHub's web editor (press `.` in the repository, or use the edit
+pencil on any file) and open the PR from there.
+
+# Content Organization
+
+The SEAMS site content is organized into several `jekyll` collections:
+
+ - warmups (`_warmup`): mental calisthenics.  As the name suggests, the warmup exercises for each day.  short puzzles.  code katas.  etc
+ - topics (`_topic`): brief outline of a concept + reference links.  for use outside of discussion session
+ - sessions (`_session`): material for discussion sessions -- anything people need to download, stuff to display, questions, etc
+ - practicals (`_practical`): toy problems to focus on particular topics - paired with the discussions to help participants focus on the particular SE concept we discussed, and prep them to apply that thinking to their project
+ - project (`_project`): guided work for participants particular projects
+
+To learn more about collections, [see this](https://jekyllrb.com/docs/collections/).  The gist of our use, however, is
+
+# More Details on the Blocks of Content for the Course.
+
+ - Reference Material (`_topics`):
+  * meant to be read-ahead and take-away
+  * develop a reference list / reading material / etc page
+ - Sessions / Discussion (`_session`):
+  * provide the rough pitch why the participants should care about this topic / perspective, and how they should think about it
+  * visit ~10 high level concepts within that topic, and how they work together (& with other topics)
+  * plan opportunities for interactive learning on these concepts: some mini task (~1-3 minutes) in pairs, or full cohort Q&A (~5 minutes), etc
+ - Practical (`_practical`):
+  * have an on-computer exercise, working with a toy problem
+  * should build in complexity; at least 3 levels that everyone will do, with a few more for people that really get it
+  * should NOT entail a lot of keystrokes to do right; the practical time should mostly be people struggling with new concepts / approach, not rapid-fire typing
+  * will need to prep code and input in addition to directions
+ - Project:
+  * provide a list of questions / tasks to give to participants to apply to their own work
+  * these questions should also suggest how the results can be incorporated into project
+  * also need a rubric / guidance / etc for other faculty to evaluate against to help them provide feedback to participants
+
+# Some Example / Reference for Blocks of Content
+
+Project Planning & Design Session, ~10 concepts might include:
+ 1. Requirements
+ 2. Separation of Concerns / Design Patterns
+ 3. DRY vs KISS vs Too-Much-Magic
+ 4. Testing - validation vs verification vs performance (overlap w/ workspace org - having testing infrastructure),
+ 5. process / work flow maps & pseudo code => real code
+ 6. documentation (overlap w/ workspace org)
+ 7. distribution (overlap with reuse & reuseability)
+ 8. general coding best practices (conventions), etc...
+
+mini exercises: code "telephone"
+
+Project planning & design practical: toy problem to do with morse code.  tasks: figure out work flows for parse, then de-parse, then identify overlap, then propose useful separate of pieces (e.g., reference non-code file for translation map, input / output separate from core dot-dash to alphanumeric and vice versa
+
+Project planning & design applied to their project, example tasks:
+- draw the flow diagram for each of the pieces your research work associated with this project, including inputs, outputs
+- across those flows for each part, identify the "conserved" pieces
+- list the requirements for your project: what kind of inputs must be used? what sort of outputs?  what analysis rules must be met?
+- what are possible intermediate products in your work? what are the dependency relationships between those pieces?
+- what part of your project is specific?  what part is generic to similar problems?
+- what is the 1 sentence description of your project? ...the 1 paragraph? ...the 1 page?
+- who is the audience / customer for this work? how will they use the work? what context do they work in?