marolAI / seams-workshop.github.io

---

Repository for SEAMS website using GitLab Pages.

Learn more about GitLab Pages or read the the official GitLab Pages documentation.

---

TODO: figure out doctoc

Table of Contents generated with DocToc

• Getting Started
  • Start by forking this repository
  • Start from a local Jekyll project
• GitLab CI
• Using Jekyll locally
• GitLab User or Group Pages
• Did you fork this project?
• Other examples
• Troubleshooting

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. 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?

Editing

To avoid blowing anything up, we're using the general following workflow:

1. make a plan for some finite chunk of work you will do (e.g., editing some particular discussion material)
2. fork / branch the repository, depending on permissions
3. edit (again: should be small chunk of content)
4. make a merge request
5. maintainer will sort out any commit conflicts
6. if appropriate, changes merged
7. delete the fork
8. return to 1.

Editing online

You can just edit in the browser via gitlab:

2. go to gitlab.com/SEAMS-workshop/seams-workshop.gitlab.io
3. use the "fork" button (right-ish on the list of things to do), or create a new branch (next to the repo name, the little dropdown menu with the plus, select new branch)
4. if forking: should send you to your namespaces to clone under; select the appropriate one, and a new fork of the repo should appear under that namespace.
5. click on the (Web IDE) button (left side, after repo front matter, but before most recent commit message)
6. edit the relevant files.
7. when done editing, click the commit button (blue, lower left; alternatively, there are context buttons on the left to switch between edit, review, and commit)
8. hover over "unstaged commits" to reveal option to stage all changes (alternatively, click the check beside each file change you wish to include)
9. enter useful description of edits in commit message box. the headline / summary will be the first line (if you're overlength, the message box will highlight your excess). subsequent lines will be the longer message text (if necessary)
10. leave the branch selected (master if you forked, or whatever you named the branch), then click green commit button.
11. return to the repository view (top left button in the Web IDE context, next to the repo name)
12. click the merge request button (the standard graphics for showing git branches; looks a bit like public transit routes)
13. should see option to create a new merge request - click the big green button
14. should show your local repo on the left (if forking) or new branch (if branching), and the main repo / branch on the right; on the left, select the branch you made edits in (should be master if forked, otherwise whatever you created)
15. click "compare branches and continue"
16. in the next chunk, just fill in a brief title for your collected commits, then any other detail pertinent in the larger textbox (e.g., an issue number in the format #N if you're making changes to resolve a particular issue)
17. after this, request the merge, and someone will review it in the main repository. If you need to make more tweaks to this particular work (i.e., correcting spelling, path to some image), you can use the process above starting after the "fork / branch" step. As long as the merge request hasn't been completed, any additional work you do will be included.

Editing locally

You can work via whatever local tool you prefer:

2. make a local clone of gitlab.com/SEAMS-workshop/seams-workshop.gitlab.io
3. make an editing branch git checkout -b 'demo-local-editing'
4. edit the relevant files.
5. when done editing, stage the changed files git add file1 file2 etc
6. commit the files (git commit either with -m flag or using whatever editor when the message comes up)
7. push your new branch: git push --set-upstream origin whatever-you-named-the-branch
8. for the merge request, you should probably use the web view (there are some CLI tools, but nothing supported directly by gitlab). Follow the directions for editing online.
9. If you need to make more tweaks to this particular work (i.e., correcting spelling, path to some image), you can use the process above, but just use git push (instead of all the extra args) when updating the origin. As long as the merge request hasn't been completed, any additional work you do will be included.
10. after your work has been accepted, development branches will be deleted in the origin repo. To start on your next chunk of work, return to the master branch, pull (to get your updates), and then create your next working branch: git checkout master && git pull && git checkout -b 'new-branch-name'. You should also delete your now-accepted old branch: git branch -d whatever-you-named-the-branch

Getting Started

You can get started with GitLab Pages using Jekyll easily by either forking this repository or by uploading a new/existing Jekyll project.

Remember you need to wait for your site to build before you will be able to see your changes. You can track the build on the Pipelines tab.

Start from a local Jekyll project

1. Install Jekyll.
2. Use jekyll new to create a new Jekyll Project.
3. Add this .gitlab-ci.yml to the root of your project.
4. Push your repository and changes to GitLab.

Using Jekyll locally

To work locally with this project, you'll have to follow the steps below:

1. Fork, clone or download this project
2. Install Jekyll
3. Download dependencies: bundle
4. Build and preview: bundle exec jekyll serve
5. Add content

The above commands should be executed from the root directory of this project.

Read more at Jekyll's documentation.