s24 Legacy Project Launch

On Wednesday May 15 2024 at 4:00PM, in section, we’ll launch the legacy code projects.

This page describes how that will roll out.

Due Date

The due date for getting PRs in, green on CI, and reviewed by a member of your student team is Thursday May 30 2024 at 5:00PM, i.e. at the start of class that day (typically the last class day of week 9).

After that, you may only:

Work on existing PRs to address issues raised by the staff in code review
Add new PRs if and only if approved in advance by a staff member to address an issue raised during a code review of an already existing PR.

Taking on new work after that point is not permitted, since we need time for the staff to review the work already completed, and get it merged so that you can make your final release notes and final video presentation.

Links

Open this section for links to the legacy code project resources

Section: 4pm (proj-courses)

Team	Repo	PRs	Github Pages	Kanban	Dokku Prod	Dokku qa
s24-4pm-1	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-4pm-2	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-4pm-3	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-4pm-4	repo	PRs	github pages	kanban	dokku prod	dokku qa

Section: 4pm (proj-happycows)

Team	Repo	PRs	Github Pages	Kanban	Dokku Prod	Dokku qa
s24-4pm-5	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-4pm-6	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-4pm-7	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-4pm-8	repo	PRs	github pages	kanban	dokku prod	dokku qa

Section: 5pm (proj-organic)

Team	Repo	PRs	Github Pages	Kanban	Dokku Prod	Dokku qa
s24-5pm-1	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-5pm-2	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-5pm-3	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-5pm-4	repo	PRs	github pages	kanban	dokku prod	dokku qa

Section: 5pm (proj-gauchoride)

Team	Repo	PRs	Github Pages	Kanban	Dokku Prod	Dokku qa
s24-5pm-5	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-5pm-6	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-5pm-7	repo	PRs	github pages	kanban	dokku prod	dokku qa
s24-5pm-8	repo	PRs	github pages	kanban	dokku prod	dokku qa

The Assignment, Briefly.

In this project:

You will be assigned a legacy code base, and a set of issues (new features, refactorings, bug fixes)
The list of issues contains more work than we expect you will need to complete in order to get a perfect score on the project, so don’t worry that you have to finish them all; you do not have to finish them all.
Some of the issues are “epics”, which is a higher level than an issue: it’s a group of related issues. It is the responsibility of the team members to take the epic and create smaller issues from it, copying/pasting the relevant parts and the editing the file to turn it into smaller single issues. Each of those should usually be merged in its own separate small PR, not as one giant PR at the end.
Each issue you complete earns points for your team after it is:
- code reviewed and approved by a member of your team that didn’t work on it
- code reviewed and approved by a member of the course staff (instructor, TA, LA)
- merged into the main branch of your repo.
Issues earn different numbers of points: typically, 5, 10 or 20 depending on the complexity of the issue (more on this below).
There may be a few issues that are marked as “must do”. You must complete these or their point values will be subtracted from the points you earn. These are assigned point values in advance.
For other issues, points are assigned after completion. If you want to ask for a point estimate, you may do so, but keep in mind that actual points can differ from estimated points.
Unlike in previous team projects, where your Issues list and Kanban board may have been pre-populated with issues by the staff, in the legacy code phase, populating the Kanban board is the responsibility of the team. More on that below.
The aim of the team is to earn 100 points before the deadline. This forms the most important part of you project grade, which is 25% of your course grade.
Another part of your project grade is your “CATME multiplier”, which is a number based on your peer evaluations. This number is typically 100 unless your team has rated you significantly below the team average
Points beyond 100 can count as extra credit as explained below.

Points beyond 100

If you accumulate more than 100 project points, the additional points may count as extra credit, at a rate of 1 extra credit point for each 10 points over 100 earned, up to a maximum project grade of 110. For example:

Points Earned	Project Grade
80	80
90	90
100	100
105	100.5
110	101
115	101.5
150	105
180	108
≥200	110

Your final project grade is maxed out at 110 total project points–any points in excess of 110 will not count towards your grade (though you’ll probably learn a lot from having under taken the work to earn them.)

Sprint Planning for Legacy Code project

Each team already has a Kanban board setup for the legacy code project (see links above). However unlike in your team01, team02, and team03 projects, it’s up to you to populate this yourself.

Populate your todo column with issues, start assigning them to your team, and start working.

You may not get through all of the Sprint planning today, but by the end of discussion section on Wednesday:

Each of the six team members should be assigned to an issue in the todo column
The previous bullet point shoudl remain true until your team reaches 100 points
This may require breaking issues out of an epic. In some cases, you may need to assign different team members to work on backend and frontend issues from the same epic in parallel, or pair-program on some of the early issues.

Teams accumulate points when PRs are merged into main

That is only done by the course staff for these projects.
Each PR requires at least one code review from a team member, and at least one code review from a staff member
The staff estimate points. Most issues are 5 to 10 points.
- 5 points for very straightforward issues addressing a single concern
- 10 points for issues that require a bit more work, but are nevertheless reasonably straightforward application of skills from team01, team02, team03.
- 20 points is rare, and is reserved for issues that may be more complex, and/or require students to go significantly beyond the skills from previous course assignments.
Note that breaking down issues into smaller chunks works to your benefit in multiple ways:
- Easy to code review and merge (fewer merge conflicts), so faster point accumulation
- Three 10 points issues and three 5 points issues adds up to 45 points; combining all of those together might only get you 20.
- But the aim here should not be to “game the points”. It should be to “get the issues implemented”, in incremental “right sized” pieces.
- If you do that, the points will take care of themselves.

Points belong to the whole team, not to individuals

Work as a team, and help each other.
We do want to see every team member contribute
Ultimately, it’s a team project and a team grade.
Having said that, really low CATME scores might result in a grade reduction.

Where do issues come from?

For issues, you’ll need to do a bit more work that in the previous team projects.

Each of your repos is populated with an issues list (see the issues tab).

These issues come in different sizes
- A handful of these may be small easy issues.
- However, many (most?) of these issue may not translate one-to-one into issues for your Kanban board.
- Instead, you are encouraged to try to break the larger ones down into smaller issues, each of which could be a single PR; more on this below.
- This Sprint Planning meeting is where you can do some of that.
- You may even need to add “issues about issues”, e.g. an issue that says: “break issue #34 from proj-happycows into multiple issues on our team’s repo”. Such an issue doesn’t result in a PR, but it can still be moved across the Kanban board from To Do, to In Progress, to In Review, to Done.
Your team’s own ideas for features; these should be vetted with a staff member before you get too far into working on them, to ensure that they are aligned with user needs. Issues that are not aligned with customer will not be merged into main and will not earn points so be sure that you vet your issues with staff if they are ones you came up with yourself.

Staff may add to these issues over the course of the project; when we do, we’ll post an announcement in the project slack channels.

You are encouraged to keep each PR small.

For example, implementing a new feature may require

A new React Component (with tests and storybook entries, and perhaps fixtures to support those)
A new React Page
- This page might start out with a simple PR that establishes a placeholder with text “New feature coming soon”, and a trivial set of tests and a storybook entry
- It might later get data from the backend and display it using a component, and be linked to from the navigation bar.
A new database table (or a new column in an existing database table, requiring modifications to an @Entity and/or @Repository class
New API backend endpoints, which require controller methods and tests.

Each of these could (and arguably should be) a separate PR! This helps to keep PRs small, which makes code review easier, and also helps the team to divide up work among the team members.

Still, you may need to document in the issues what the dependencies are (e.g. “do issue 12 and 13 before starting 14”).

Setting up dokku prod and qa instances

The staff will work with you to set up dokku prod and qa instances; that will happen on Thursday May 16.

Staff Information

Information in the dropdown below is intended for course staff. Students are welcome to look at it, but it’s really targetted at a different audience.

Staff information for legacy code phase

Creating the team repos

To set up repos for the legacy code project phase, use the https://ucsb-cs-github-linker.herokuapp.com tool. The menu option you want is “Teams // Create Team Repos”:

Team repos are created using the usual process, but the syntax is a little different. Here’s an example for S24:

Repeat for each group of teams and each project.

We assign Write permission rather than Admin permission so that the staff can control the main branch with branch protection rules.

Preparing starter repos

Each of the starter repos needs the following preparation

Set CODEOWNERS

Put the github ids of the instructor, TAs and LAs (anyone that can merge into main) into this file:

Set up branch protections

Instructions for setting up branch protections can be found here:

https://ucsb-cs156.github.io/cs156-guide/1-legacy-code-projects/3-setting-up-projects.html#establishing-branch-protections

Be sure issues you want students to work on are tagged

Check the issues list. Make a tag (e.g. S24) for the issues you want the students to work on.

Set variable to used used by workflow 99

In workflow 99, the tag gets its value from the organization variable QXX which should be set to match the tag (e.g. S24) that’s applied to the issues you want to bulk copy over.

Visit: https://github.com/organizations/ucsb-cs156-s24/settings/variables/actions to set that value, e.g. to S24

It should look like this:

Why we don’t create team repos with a fork

We don’t use the fork approach for this reason: If we created the team repos as forks, then every time students create a PR, the default would be a PR back to the main repo. This would be fine if each of the teams was working on an independent set of tasks, but if the design is to have each of the teams work on the same set of tasks, then their PRs would clash and be redundant.

So, instead, we create independent repos in the course organization for the class offering (e.g. https://github.com/ucsb-cs156-f23, or https://github.com/ucsb-cs156-s24, etc.) that are initially populated with the main branch of the repo from the https://github.com/ucsb-cs156/ organization.

Set up project channels

In the Slack workspace, set up channels for each project:

You can click “Skip for Now” and add folks to the channels later, or invite the students and staff to add themselves to the channels.

Then, update the links at the top of this page to the project slack channels (in the front matter):

Copy the link to the channel:

And then configure in the front matter of this page:

proj_courses_slack_url: https://ucsb-cs156-f23.slack.com/archives/C066057BBHA

Repeat for every project.

Setting up Kanban boards

To set up Kanban boards for the legacy code project:

Make sure your github organization has a suitable template, i.e. a Kanban board set up with the views you want. For example, this one: https://github.com/orgs/ucsb-cs156-f23/projects/28/views/2
Navigate to the template board so that your screen looks like this:
For each team, click the Use Template button, and in the box that comes up, paste in the name of the repo for which you are creating a Kanban board; for example, pasting in proj-happycows-f23-5pm-2 as shown here. Also be sure that the owner is the github org for the course, e.g. ucsb-cs156-f23:

A kanban board will be created:

Repeat for each team. To make this efficient, you may find that hitting the back button gets you back to the page where you can click Use Template; have the previous project name in your copy/paste buffer so that all you have to do is change the team number.
If you do these operations consecutively, in order from first to last team, you’ll get a range of project numbers, e.g. twelve projects ranging in number from 43 to 54.

Add project numbers (kanban board numbers) to Front matter

Next, put these numbers in the front matter of this page. For example (only a portion of the yml shown here):

      time: 7pm
      product: proj-courses
      productShort: courses
      teams:
        -
          num: 1
          dokku: "09"
          kanban: 51
        -
          num: 2
          dokku: "10"
          kanban: 52
        -
          num: 3
          dokku: "11"
          kanban: 53
        -
          num: 4
          dokku: "12"
          kanban: 54

Link the kanban board to the repos

For each repo, visit the repo page and link the repo to the kanban board.

For example, on the repo page, click the Projects link:

Find and click the Link a Project button:

Use the search box to find the project that matches the repo:

Click to link the repo to the project.

Set access for teams to project

For each project you’ll need to set the team to have access.

If you’ve already configured the kanban board links on this page (following the instructions above), you can use this process to do this efficiently:

Open the top of this page in its own browser window
Use the “Open link in new tab” to open up each kanban board in its own tab, until you have twelve tabs next to this page, one per kanban board.
For each kanban board, set the permissions, then close the tab.

Here’s what opening all the tabs looks like:

open-each-kanban-board

Here’s what to do on each kanban board:

Click Settings (upper right)
Click Manage Access (left navbar)
Find the ``Invite Collaborators search field; (or copy/paste) the team name (e.g. f23-5pm-1`) into it
Select the team, change Role to Admin in the dropdown, and click Invite

Here’s what that looks like:

set-each-kanban-board-permissions

Populate repos

Using a script such as the following, populate the repos from the starter code. Repeat for each project and group of teams.

#!/bin/bash

teams=" \
 f23-7pm-1 \
 f23-7pm-2 \
 f23-7pm-3 \
 f23-7pm-4"

project=courses
starter=https://github.com/ucsb-cs156/proj-${project}.git

for t in $teams; do
  echo "******* team: $t start ********"
  r=proj-${project}-${t}
  git clone git@github.com:ucsb-cs156-f23/${r}.git
  cd $r
  git checkout -b main
  git pull origin main
  git remote add starter ${starter}
  git pull starter main
  git push origin main
  cd ..
  echo "******* ${t} end ********"
done

Set up Github Pages

For the next step, we suggest opening each repo it its own tab (similar to how we opened a tab for each kanban board above).

For each repo:

Go to the Actions tab
Select the job 02-gh-pages-rebuild-part-1
Trigger it to run manually from the main branch

Here’s what that looks like. Note that as shown in the animation, there is a short delay between when you click to run and when the job shows up. Don’t make the mistake of being too impatient, and then ending up running the job twice.

trigger-job-02

Job 02 should trigger job 04 to run, to build the gh-pages branch; you’ll then need to manually enable github pages (which we will do in the next step.)

It is not unusual to have a few failures on the first few runs of job 02 or job 04; just re-run the job if that happens. If it fails repeatedly, you may have a real problem, but typically just re-running takes care of these as long as the repo is in good shape.

Enabling github pages

As soon as jobs 02/04 complete (even partially), a gh-pages branch will be established. You can then enable github pages for each repo by following these steps:

Go to Settings for the repo (top nav, right most link)
Go to Pages (left nav, halfway down)
Under Source select Deploy from a branch
Under branch select gh-pages and for directory select root. If gh-pages is not present, wait for job 02 and job 04 to run and establish the branch.

Here’s what that looks like: setup-github-pages

Set link to github pages on repo

For each repo, select the checkbox on the main page to set up a link to the github pages site by following these steps:

Navigate to main page of the repo
Click the Gear icon at right near top of page next to About
Click the checkbox on the form next to Use your GitHub Pages website

Here’s what that looks like:

link-to-gh-pages-from-home-page

Populate the issues

First, check that the issue for the project are the ones you want, i.e. that you’ve marked the issues in the starter repo (e.g. https://github.com/ucsb-cs156/proj-happycows ) that you want the students to work on with a tag such as f23.

Second, check that workflow 99 has the correct tag in it (near the top). (We should probably do this before we populate the repos! If you find that you didn’t do this, there’s a script below to fix this; or you can just fix it manually in each cloned repo):

Finally, run workflow 99 to populate the issues list:

When it finishes, the issues that were tagged with for example f23 should appear in the issues list. Student can then add them to the Kanban board as they see fit.

Updating the repos

If it’s necessary to pull code from the starter repo a second time, this script can be used:

#!/bin/bash

teams=" \
 f23-5pm-1 \
 f23-5pm-2 \
 f23-5pm-3 \
 f23-5pm-4"

project=happycows
starter=https://github.com/ucsb-cs156/proj-${project}.git

for t in $teams; do
  echo "******* team: $t start ********"
  r=proj-${project}-${t}
  cd $r
  git checkout main
  git pull origin main
  git pull starter main
  git push origin main
  cd ..
  echo "******* ${t} end ********"
done

Special steps per project

For courses

You will need to generate a UCSB_API_KEY for each of the teams and share it with them on their slack channel. They will need this key in order to set up their localhost deployment and their dokku instances.

To create a UCSB_API_KEY, you’ll need an account at https://developer.ucsb.edu. To create the key, follow these steps:

First, navigate to the apps page:

Click Add App

Fill in the team name. You can leave the rest blank, then scroll down to the APIs checkboxes.

Click to choose the APIs to enable.

Then click “Add App” at the bottom:

You will also need to set up a MongoDB database instance (or else give them instructions on how to do it themselves.)

Updating Slack Channel topics

For each team channel, update the “Topic” to be initially this (changing the link in each case). This gives you a place to keep track of the total points assigned, and a convenient link to check the PR queue: e

0/100 pts - PR Queue: https://github.com/ucsb-cs156-f23/proj-happycows-f23-5pm-1/pulls

Cycling through the team channels

Throughout the legacy code phase, the staff should cycle through the 12 to 16 team channels, checking the PR queues.

The pseudocode for the (manual) procedure is something like this:

for team in teams:
  From team's slack channel, click link to team's PRs
  for PR in PRS:
     check(PR) (see process below)

def check(PR):
  if PR (is not green on CI) or (does not have a peer code review) or (has other problem preventing staff review)
    add red warning labels as needed; return
  perform code review
  if code review passes:
    assign points (using a gold colored label)
    merge PR
    update topic on team channel

When updating the topic of the team channel, add the points in to the 0/100 pts part.

If it’s the first time that the team had a merged PR, add a link to the PRs that were merged (e.g. https://github.com/ucsb-cs156-m23/proj-gauchoride-m23-9am-1/pulls?q=is%3Apr+is%3Amerged+, and add a bookmark to the full PR queue on the team channel.

Setting up Dokku Deployments

We typically set up the following deployments as staff:

Prod and qa deployments on dokku-00 for the repos in https://github.com/ucsb-cs156, e.g.
One prod and qa deployment per team
- The prod deployments are intended to track the main branch. It would be desirable, if possible, to set up a cron job to automatically deploy these periodically, or a github action that redeploys them whenever a PR is merged to main, if either or both of those can be done without creating a security issue. The names are, for example:
The qa deployments are intended for staff use when reviewing PRs.

The students are then encouraged to set up personal deployments using the project name and their github id for personal dev testing, and demoing PRs under review. For example:

Students may create additional deployments if needed.