Skip to content

Workflow

Jump to bottom
gabeclasson edited this page Dec 26, 2022 · 20 revisions

Overview

The lifespan of a worksheet consists of three weeklong stages:

  • Writing: the worksheet content is created. This is where 90% of your work is done.
  • Review/buffer: the worksheet is sent to reviewers for review. Their feedback is considered, and the worksheet is revised. The worksheet is presented at the SM-coord meeting.
  • Deployment: the worksheet is taught to mentors.

Worksheets are named for the week where they are deployed; therefore, mentor02 is the worksheet that is taught during the second week in the semester. Because of this timeline, you must begin work on the worksheet two weeks before the beginning of the worksheet's deployment. That means that if sections begin during week 2, you must begin writing the worksheet during week 0 (the week before the semester begins). Here is a visualization of how that workflow shapes up in that case:

image (Note that mentorXX is always deployed during week XX? That's no coincidence.)

Because one worksheet is deployed each week, the weeks layer together so that you have one worksheet in each of the three stages each week. (Students who have taken CS 61C will recognize this as "pipelining".)

Calendar

Concretely, the workflow cycle for producing mentorN will consist of the following steps:

  • Week n - 2 Monday: Worksheet draft is started.
  • Week n - 2 Friday: Worksheet draft is finalized and is presented to reviewers for review.
  • Week n - 1 Sunday (end of day): Worksheet review is due from the reviewers.
  • Week n - 1 Monday: The worksheet is finalized and presented to senior mentors. It is now up to the course coordinators to handle final distribution of the worksheet.
  • Week n - 1 Friday: All slides and other materials are completed.
  • Week n Monday: Sections begin to teach mentor n to students, and the worksheet is publicly released.

Pre-composition

Before you write the worksheet, you must review the past semester's work (refer to the most recent semesters, su22, sp22, fa21, and go back further if needed)

  • Review those previous semesters' worksheets. In some cases, topics were covered on different dates and combinations.
  • Review stale branches and unmerged pull requests from previous semesters for possible improvements not reflected in main.
  • Review any issues relating to this worksheet's content (note that week numbers may have changed from semester to semester).

Note: We strongly suggest you use Github Desktop for everything Git-related for this repo

Drafting

  • Create a branch to store the current worksheet's work.

    • In GitHub Desktop: Click on Current branch and select New branch
    • Name the branch fa22/mentorXX (ex. fa22/mentor03). The week number of the worksheet should correspond to the week number of the course when the worksheet is taught. That is, if students see "Week 2" on their worksheet in CSM section, they should also see "Week 2" on the CS 61A website at the same time. (Note that this may cause you to skip some week numbers.)
    • There should be a new popup with the button Publish Branch, click on that.
    • There should be a new popup in the same place with Create Pull Request
      • Once you have made some changes you can click on that button and open a pull request entitled [fa22] mentorXX
      • Please add the worksheet label to the PR.
      • Add relevant issues to the worksheet under the "Development" field.

  • Once you have made some changes, you can make an individual worksheet by running the following command in the repository's root directory.

    make mentor00

  • To create all content for one week, you can pass multiple parameters into the make command in the repository's root directory.

    make mentor00 mentor00_meta mentor00_sol

  • As you update the worksheets, please commit your changes as you go. A general rule to follow: No commit is too small.

    • As you go one and create changes, please commit them along with descriptive commit messages
    • Good Example
    • Bad Example (Note this example has nothing to do with CSM, but shows what you should not be doing)
    • You can push your commits via Git Bash, but it is much easier with GitHub Desktop, where you can see all of your revisions and the files you modified in one place, and from there you can choose what you want to commit and with what message

  • For styling and formatting the worksheet, please refer to the style guide.

  • For guidance on how to write a good worksheet, please refer to the worksheet content guide.

Worksheet review

When the draft of the worksheet is done, attach PDF copies of the worksheet, solutions, and meta to the pull request in a comment.

image

Then add the reviewers to the PR [This will be updated to reflect who should be reviewing the worksheet].

image

Finally, send a message to the reviewers requesting their review and spelling out the due date. Here's a possible message template:

Hi, [REVIEWER], I just requested your review on the worksheet for week [WEEK NUM]. You can find the PR here: [PR URL]. Please review the worksheet by EOD Sunday according to these instructions: https://github.com/csmberkeley/csm-61a/wiki/Worksheet-review. Let me know if you have any questions and thanks for all your help with this!

Finalization

  • After receiving the review, make any last changes to the worksheet before presentation to the SMs.
  • Make the worksheets, and place them in your semester's folder in published.
  • Merge the branch into main.
  • Upload the worksheets to the content Google Drive folder.
  • You may delete the branch at this point (but I'd recommend waiting a few days).
  • Once the worksheets are printed, you should not continue to change the content. However, fixes to the solutions and metas may be made up until sections end.

Slides

Slides should be completed before sections begin each week. You should not need to remake slides each semester. Old semester's slides should be passed down from SCM to SCM. If you do not have access to last semester's slides, ask your coord or the previous SCM. For posterity, here is a read only copy of the slides from Fa22: https://drive.google.com/drive/folders/1MzeVa401H6jwoX6FWaLkvmL-d_eiTzKy?usp=sharing

Post-section feedback

  • Collect feedback from mentors through a Google form.
    • Write a new issue detailing these fixes. Title the issue "[fa22] mentorxx (TOPIC)" (e.g. "[fa22] mentor03 (Environment Diagrams and Higher Order Functions)"). Add the worksheet fixes label.
    • For each problem you critique, mention the canonical name of the problem (the name of the question file in topics). For example: funky-funcs. This improves searchability.
    • If you have the bandwidth, you can fix particularly egregious problems at this point. However, under you should not change the final worksheet PDFs in the semester's folder. We're not here to rewrite history.
  • Close or merge all pull requests used for the worksheet, and then delete the branch.
  • Close any issues relating to the worksheet that are no longer relevant.

End of semester

Some previous semesters did not maintain this repository as well as they could have. We're going to do a better job of that. At the end of the semester, all pull requests should be closed or merged, and all branches should be deleted. Additionally, all irrelevant issues should be closed.

Major Contributors: Aditya Balasubramanian and Gabe Classon

Clone this wiki locally