Skip to content

Home

Jump to bottom
Katrina Connors edited this page Sep 17, 2024 · 23 revisions

Last edit September 17th, 2024

Compass Logo

Welcome to the Compass GitHub Wiki!

Compass is a civic app we are building for the San Francisco Unified School District. The app seeks to assist Teachers with setting and tracking goals for students with disabilities.

Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Fine Tuning Your Code
  4. Resources

About The Project

Hello, Engineers and Designers seeking to contribute to the Compass app! This Wiki is set up to guide you on how to contribute to the repo, and will hopefully answer a few of your questions as to what phase the project is in and how to self-assign issues and build out components. This wiki will be updated when possible, revision date noted at the top of the Wiki.

Note: Designers

Most of the information on this home page is directed towards how to contribute as a Software Engineer. For Design-Team-Specific Documentation, head to the Design Team's Page in the wiki, or join the Compass Slack channel, links at the SF Civic Tech site.

Project Overview

Project Compass is a web app designed to make it easier for Case Managers (Teachers) and Para-educators (Teachers' Assistants) in a school district to set and record a student's progress towards their IEP (Individual Educational Plan) goals. The IEP goals are established annually in meetings with the Case Managers and the Stakeholders (Usually the parents and any specialists).

Historically, Case Managers (CM's) would use spreadsheets to store students' progress, and would print out a list of activities and give it to the Para-educators (Paras) along with verbal instructions. The Paras would then use these instructions and lists to have set activities with the students, reporting back on the student's progress when they had time. While handling the IEP data collection this way works, data collected this way can be lost easily and it can be challenging for the two parties to communicate and adapt to situations like absences and progress hiccups. Per our research interviews, a CM's and Para's schedules might not match up during the day, and sometimes a Para or CM could have a challenging class and not have the time or attention available to collect activity data if they have to handle paperwork as well as the class.

The Compass app seeks to make CM's setup of the data collection activities straightforward, but most importantly seeks to make the activity data collection for the Paras fast and simple. After allowing for easy data collection, the Compass app will graph that data for the CM to have an easy visualization of the students' progress on each Benchmark (the activities that lead toward a student reaching an IEP goal). This way, the CM can be quicker to adapt and adjust the activities for the student, and can compose Progress reports for the stakeholders. You can learn more about it at the project’s original Notion

(back to top)

Current Teams

Compass is split up into five teams, though we currently all meet together weekly to update all teams on progress. Most teams also have a separate meeting during the week. You can find out more on our Slack, which you can join on our site here

The teams are:

  • Groups 1 - 3 - the project is currently split up into the different views our app will present:
    • Group 1: The Staff Benchmark Assignment (aka Case Manager View) - A web app with a browser-first view, for the setup of the Caseload and assignment of the Benchmarks.
      The Caseload consists of:
      • Students and their IEPs. (The students are unique to the Case Manager for that school year)
      • Para-educators that the Case Manager assigns to data collection for a student on the Caseload (Some Paras assist more than one CM)
    • Group 2: Benchmark Data Collection (aka The Para-educator View) - A web app with a mobile-first view, for the Para to collect data (And the CM if they are so inclined)
    • Group 3: The Data Visualization - Graphs and charts for the CM View to visualize the collected data
  • Design Team: Handling the styling and visual layout of the different parts of the app
  • Tech Team (Us!): Programming and deploying the app!

Current Project Status

We are currently in the middle of the build and could use the help! Much of the design for the three different groups has been done, but the engineers need to both refactor what has been built to the updated specs, and also build out the features that are not yet functional or present.

Tech Stack

  • TypeScript
  • React
  • Next
  • tRPC
  • Node
  • PostgreSQL
  • Zapatos
  • Docker (optional for installation but required to have on your desktop for testing to work)
  • Ava (for back-end testing)

(back to top)

Getting Started

Please use the Repo's README to handle installation. You must contact a team member on Slack on our proj-compass-tech channel to get Auth working (the team member will need to add you to the repo/Compass Engineering team); without logging in with the right credentials, you will get Auth errors and may be redirected to the Sign-In Page. You will also need to create your own Google Client ID and Secret for the project, set up for a web applicaton.

Special Note Regarding Auth

If your Auth worked and then suddenly it does not, it may be that the cookies in your browser are not reflecting the current Auth correctly. This will especially be the case if you migrated the database since the last time you signed in! You can enter the following command into your browser, which will direct you to the cookies for localhost so you can clear just them.

chrome://settings/content/all?searchSubpage=localhost

Tech Team Agreement

AKA How to Manage Your Time and Energy as a Contributor

Since this is an open-source project, we are all here voluntarily in our spare time, which can contribute to a loss of both communication between team members and persistence on tasks. These things sometimes make things Less Fun For Everyone. In order to alleviate pressure and still keep the work flowing and interesting, this addresses your responsibilities as a team member, so you can rest easy knowing you are doing the right thing if you want to step in or need to step away. Click here to move on to Using GitHub Issues

If You Have Self-assigned An Issue:

Please:

  • Communicate Progress or blockers EARLY AND OFTEN with your teammates and your component's Designer(s), on the slack channels, and in meetings! :)
  • We encourage making SMALL PR's. You can break an issue down into separate tasks, like the implementation, the CSS, and the testing. If you see work outside of the scope of your ticket, don't rope it in! Make an issue ticket, write it down to bring it up in meetings, or communicate it on Slack. Doing too much work on one ticket causes PR bloat, is hard on your colleagues, and may mean your PR does not pass code review.
  • We suggest you make TODOs rather than trying to make a PR perfect - if your PR passes the checks and solves the implementation requirements, submit the PR and make small TODO issues for more work. This gives you or another engineer another opportunity to contribute.
  • Have 2-4 assignees working on each issue. That way one of you can advocate for it or check in on it if the others can't make it to any meetings that week.
  • Be aware of your commitments, don’t commit to too many things at once, and also let the tech team know via the Slack Channel if you have to step back, even for a few days. This allows others to step forward and get experience.
  • When you meet up to pair-program, agree on how you will handle Code Reviews: E.g.: If the person submitting the PR will be responsible for addressing comments or if the other contributors can address comments.
  • Even if the main ticket issue is not resolved, if your code is a good start and passes the checks locally, push any Liveshared code to your issue branch in GitHub after a group session, even if you are not ready for a PR, so your teammates can access it. Do this even if you plan on working on it solo later. (Simply communicate what your future plans are with your team)
  • Feel free to create new issues for TODOs or Bugs if your group PR has already been submitted, or push those fixes up to the same branch if the PR is still open and is not reviewed.
  • Have teammates communicate what everyone plans on doing before the next meetup, ESPECIALLY before any meetings.
  • If you have something come up in your life? To prevent a bottleneck or duplicating our efforts, Let your teammates know AS SOON as you know if you cannot work on your part. Maybe they have more time than you, but even if not, at least you’ll all know what’s up.
  • Communicate with your colleagues about any complex Code Review comments and agree on who will address them - You CAN include the reviewer in these discussions if you need clarity! ;)
  • If none of you have the time or energy to address Code Review comments, open it up to the tech group on the Slack Tech channel. We’re all here to contribute and this may give someone the chance to help that they were hoping for.
  • Be realistic about your energy and time - You don’t HAVE to let other engineers fix your code or implement your ideas, but you WILL have more chances to do cool things later if you can’t implement something at this time.
  • You may find your solution creates non-breaking bugs while still solving the issue. As long as your PR passes the tests, PLEASE submit the PR, with a comment about the bug. Then you can create a bug issue afterward, linking/noting the branch of your PR, and you’ll be giving another engineer a chance to work! If they can’t, you can always fix the bug after your PR has been merged.
  • If your team has a PR that seems stuck in Code Review, reach out to your teammates to check on them

TL/DR: Communicate fast and early and have fun with this project. Be real and quick about acknowledging your available energy and time, to yourself and to your teammates. Everyone is looking for more ways to help and if you have to step away, they would be as relieved to have the opportunity to contribute as you would be to be able to not stress about it.

If You Want To Contribute?

  • If you see a PR or issue that seems stuck in Code Review, the code and comments look fixable, and no new commits have been pushed up for a week or so after comments have been created, reach out to the assignees via Slack or during a meeting and let them know you’d love a chance to help
  • If the above team cannot get back to you in 2-3 days, address the tech group on Slack or at one of the many meetings to check to see if those folks are ok - it’s possible the teammates DM’d someone else about a change of plans due to unforeseen circumstances, and the person they messaged hasn’t had a chance to tell the group.
  • Once you have the go-ahead from the assignees or the tech team to tackle the bottleneck, follow the steps in Co-authoring
  • Feel free to update the tech channel with your intentions.

Using GitHub Issues

Our Projects board is here: Compass Project Board

The Projects board contains issues for the Eng Team as well as other Compass teams, like the Design Team. Eng team issues are discerned by the ending the green "engineering" label. The Project Board has two tabs to see the issues in different formatting: Eng open issues is a list of the issues and Eng Open Board is a Kanban board version.

You can add issues to the "Todo" list as they become obvious from meetings and discussions of the app. More will be added now that the 3 View groups are together.

  • Try to be clear in describing the issue you are creating, and include any steps you think need to be taken into consideration. (Feel free to use markdown language to create bullet points and checkboxes. Include diagrams where possible - you can copy/paste an image into a comment and GitHub will create a link for it.
  • Try to break down issues into components that can be built within 1-2 week sprints, and make extra Task issues to handle the different parts of the implementation, like the component, the CSS styling, and the testing.
  • You convert a drafted issue into an issue by clicking "Convert to Issue" once you have clicked into your draft, in the menu on the right.
  • You can self-assign an issue by clicking "add Assignees" on the upper right menu once you are in an issue. (You will not see this option in a draft). Please ALSO assign the designer if you know who it is and if they are on GitHub.
  • Please try to have 2-3 people per issue and either pair program (or work asynchronously with great communication) with your fellow engineers. This is how we learn and support each other and also how we get the work done.

Adding Components

  • File structure - src Most files we will be using are in the src folder:
    • pages (frontend URLs) The components we are building are going to display inside of the components in the "pages" folder. In Next.js, the pages folder creates the URLs to which users navigate.
    • Components (frontend component builds) Most of the components that render into the different views and the user-action handler functions will "live" in the "Components" folder.
      • As with React, you can pass props, including functions, but passing props in TypeScript and with Next.js has to be done with interfaces or types and deconstructed, like:

** Parent Component **

return (
<div>
  <ThisSpecificForm onSubmit={handleSubmit} title={title} />
</div>

** Child component **


interface Props {
  title: string;
  onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
}

const ThisSpecificForm = ({ title, onSubmit }: Props) => {
  return (...)
}

export default ThisSpecificForm;
  • File structure - src (cont.)
    • Backend
      • db/migrations/1_initial-migrations.sql The tables we will be using in our database can be added to and altered via the schema in this file. If you are changing the tables in the database, edit these files, and then remember to migrate your local database(npm run db:reset) and then bring up the change in Slack. For right now, data consistency is not important, but once we go to Production, we will have to retain the user data. If you'd like to seed your database with test data, you can use the seed script to do so(npm run db:seed). This should be done after logging into the app, so that a user exists in the user table.
      • Routers
        • The asynchronous database queries are written here in Kysely. These files will be where you write your back-end functions.
        • When making a new API, please write an API test or two in another file in "routers", named "myfilename.test.ts" (changeout "myfilename" with your back-end filename). See the ava docs for reference or review the other already-built tests in the "routers" folder to see how we are doing them. IMPORTANT In order for any tests to pass, you must have Docker Desktop downloaded and open. It doesn't have to be doing anything, just as long as it is open. Run your tests using the npm run test command.
    • tRPC queries Client-side queries are created with tRPC in the front-end components and then implemented in Kysely in the "backend/routers" folder files, which turns them into PostgreSQL SQL queries for us.
    • Styles Generally speaking, CSS for a component or page lives in that component's folder. Some small style revisions are on an issue ticket In Development to align the app styling with the Design styles in our Figma.
  • Comments: Please use comments to clarify EITHER: what your code is intended to do (though this can be solved by using good, clear names for variables and functions), or if there is future work planned and it's not obvious to anyone looking at the code.

Git Workflow

  • When you open up your app and get it running and have saved any changes on your local branch, be sure to switch to main and pull any recently merged PR's:

git checkout main

git pull origin main

  • Then create and checkout a branch for your own work, and name it something useful, like what you are intending to do with that branch:

git checkout -b newbranchname ("newbranchname" could be something like "create-benchmark-form" or "add-para-invitation")

  • Be sure to SAVE AND COMMIT OFTEN! After any significant addition or edit!

git add . (or specify the additions you want by entering git status and then only git add changedfile where "changedfile" is the specific file you want to commit)

git commit (You can use the -m shortcut if you already do or you wish to include co-author credits, but it apparently removes some of the metadata from your commit, so I am describing the "long form" commit flow) Please click here for notes on co-authoring

  • You have to hit 'i' to be able to insert your commit message. Please try to make your commit messages meaningful and generally start with a verb, like "added button to add student form" or "successfully rendered para data from specific cm's staff list".

  • Push esc and then :wq to write/quit

  • After NO MORE THAN 250 lines of code + editing (hopefully MUCH less) do a Pull Request (see below)

  • BEFORE your PR, if you do not have auto-linters set up in your VS Code settings, you are going to want to run the linters to pass the checks we have set up on GitHub. This doesn't affect your code's functionality, but it makes it consistent with the code base and thus easier to read.

Co-authoring

NOTE on Co-Authoring! If you are working on an issue with other engineers, PLEASE remember to commit with the co-author's information in mind. Get your colleagues' git-commit-specific email(s). That way they will get credit on their GitHub account when the PR merges.

Make sure to use either 1) the email they signed up with for GitHub or 2) the GitHub commit email

This is the command-line co-authoring format: note the beginning and end " quotes and the space after : In the terminal after adding your changes with git add ., write:

git commit -m "commit message goes here
>
>
Co-authored-by: NAME <[email protected]>
Co-authored-by: ANOTHER-NAME <[email protected]>"

If your colleague pushed your LiveShare code up to Github and you agreed to work on it, use terminal commands:

git fetch --all and

git checkout branchname (where branchname is the PR or remote branch branchname)

This puts a local version of that branch onto your computer. Then push your completed code up with co-authoring credits (see above) when possible:

git push origin branchname

You can find out more about co-authoring here:

Submitting Pull Requests

  • Push to your branch in GitHub (git push origin mybranchname)
  • Open a pull request and use the balloon-with-upward-arrow icon to link to the issue
  • If you re working on a smaller task inside of your main ticket issue, reference that task issue number.
  • Submit the Pull Request
  • Assign 1-2 team members to review the PR
  • Follow up on review comments, run any linters, and push committed edited code to your branch on GitHub
  • On your pull request, on the Reviewers in the upper right-hand corner, push the refresh symbol next to your reviewers to alert them that a change has been made and that the PR is ready for review again.
  • After approval, squash and merge your PR
  • Delete branch

Code Review Process

  • If you are doing a code review for another engineer, then before you start, pull and merge all code from main so that your repo is up to date, correct any merge conflicts, and save/add/commit. Then pull their Pull Request locally and see what conflicts it might have with the main repo, and run it before you look at the code to be sure there are no breaks in the functionality of the PR.

  • You can pull a PR locally by being in your main branch and typing:

    git fetch --all

    git checkout branchname (where branchname is the PR branchname)

*If dependencies were updated in the PR, be sure to run npm install

If it doesn't load, it could be that there are new permissions for your env.local that you need to get from a teammate. You can check with the engineer who submitted the PR or their teammates if it will not work.

  • Review the code for its clarity, any redundancy, good, understandable names for functions and components, and naming conventions.
  • In order to put your comments in GitHub for the PR owner to review, go to the PR in GitHub and click "Add your review". Hover over the code in question until the blue "+" sign appears, and add your comments. Feel free to distinguish between must-have and would-be-nice changes.
  • Once the PR owner has corrected any must-have changes, approve the PR. They will be responsible for squashing and merging it. (Feel free to hit them up on Slack if you want, in case they are not getting GitHub notifications)

(back to top)

Fine Tuning Your Code

Naming Conventions

Try to name your functions and components well. It's better to have a long, specifically descriptive name than a short-and-sweet name that is super generic.

  • Frontend React Components
    • PascalCase
  • Frontend handler functions
    • where the function is defined, you can name it "handleAction" where "Action" is replaced with the specific action of that function.
    • When passed as a prop, it is passed with the term "on" instead of "handle", like "onAction". See more here

<Component onAction={handleAction} />

  • Frontend "pages" URLs
    • camelCase for folders and files
    • snake_case for specific user/student pages, to align with the database property keys
  • Backend Db PostgreSQL schema
    • snake_case for property keys and table names
      • additionally, table names: we are going with the singular, e.g. "user" "student"
  • tRPC functions
    • camelCase
      • try to make these descriptive and based on the action, like get, post, update, etc.

Testing

When you are building components that interact with the back-end, please write a test or two in another file in "routers", named "myfilename.test.ts" (changeout "myfilename" with your back-end filename). See the ava docs for reference or review the other already-built tests in the "routers" folder to see how we are doing them. IMPORTANT: In order for any tests to pass, you must have Docker Desktop downloaded and open. It doesn't have to be doing anything, just as long as it is open. Run your tests using the npm run test command.

Using Linters

Before you push your code up to your branch in GitHub, be sure to run the linter. Our app is built with eslint and prettier, for clear easy-to-read code. Assuming you have already installed these, once you are ready to push your code up, run:

prettier --write .

You can then check to see that your code has all formatted with the command:

prettier --check .

If your code passes this check, it is ready to push to your branch in GitHub!

CSS OPTIONS

Try to stick with the UX/UI team's styles per the Figma as much as possible. They are here to get experience, too, and would like to be able to point to Compass as their work as well. Generally speaking, CSS for a component or page lives in that component's folder. Some small style revisions are on an issue ticket In Development to align the app styling with the Design styles in our Figma.

(back to top)

Resources

Significant Links

Glossary Of Terms

The terms below are commonly used in the app docs. For the purpose of Compass, we have established these definitions of these words for our app. Please note that these terms may be easily confused due to conflicts in meaning from earlier docs and from external sources. For the purpose of this app, go with these meanings.

Case Manager/CM: The teachers who set up the Compass app and assign Benchmarks to the Paras in their Caseloads. They usually have a mix of students, including students who need extra support. These latter students have IEPs.

Para-educator/Para: A Para-educator is a staff member assisting the IEP students on behalf of the Case Manager. Paras sometimes have specialties and can assist different Case Managers. The Paras sit down with the students to have them do the activities on the Benchmarks and use the Compass app to collect the data from those student activities/Benchmarks.

IEP: Individual Educational Plan. This is an annual Plan built with a student's stakeholders (usually the CM, parents, and specialists) for that student on the same date every year. The stakeholders gather to assess the student's current needs and areas of growth and agree on goals to help the student work on those areas.

Goal: Also called "Annual Goal," a Goal is set and tracked by the Case Manager outside of the Compass app. These goals are put into language that is NOT activity-based language, like "Get student up to 5th-grade reading level." Compass is not tracking these.

Benchmark: Also called "Task," "Sub-Goal," and "Short-term Objective," a Benchmark is a student activity or action that Paras collect data on with the Compass app to track student progress towards a goal. Benchmarks are distinguished by being an activity or occurrence, like "Have student complete 5 sentences with minimal assistance with 80% accuracy in 4 out of 5 trials." The main way to remember how to distinguish between a Goal and a Benchmark is to ask yourself "Is this an actual activity or action?" If the answer is yes, it is a Benchmark. The Case Manager decides the minimum number of Trials/Data Collection activities for each Benchmark, and regardless of how many times data has been collected on a Benchmark, decides when that Benchmark is "complete" and can be archived. **NOTE! The User-facing language uses "Benchmark" but some of the backend language uses "SubGoal". This is to connect and distinguish their relationship with Goals.

Task: A Benchmark instance as it has been assigned to a Para for Data Collection. Students have Benchmarks. Paras are given Tasks for collecting data on those Benchmarks.

Trial: A single occurrence of a Benchmark Task activity for the purposes of data collection, like one instance of the Para sitting down with the student to fill out a math or English worksheet. Paras collect data on Benchmark Tasks via Trials.

Caseload: The Case Manager's students who have IEPs, and the Paras who help them.

(back to top)

Clone this wiki locally