Skip to content

Home

Jump to bottom
Tessa Thornberry edited this page Aug 15, 2023 · 23 revisions

Last edit August 14th, 2023

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 adopt 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 Developer, though it may have some choice information for you. For Design-Team-Specific Documentation, head to the Design Team's Page in the wiki

Project Overview

Project Compass is a web app designed to make it simple/easier for Case Managers and Para-educators in a school district to set and record IEP (Individual Educational Plan) data for students with disabilities, based on the initial out-of-app IEP goals that The Case Managers and the student’s stakeholders (usually parents and any specialists) agree upon annually.

Historically, Case Managers (CM's) would use non-specific software like spreadsheets, passing the IEP activities on to the Para-educators (Paras) in the form of verbal guidance and printouts. The Paras would then use the CM's guidance to have set activities with the students, reporting back on the student's progress when they could. While handling the IEP data collection this way works okay, not only is challenging to communicate and adapt to situations like absences and progress hiccups, a CM's and Para's schedules might not match up often 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 easily.

The Compass app seeks to make CM's setup of the data collection activities straightforward, but most importantly seeks to make the data collection for the Paras fast and simple for their students' activities. After the data is collected by Paras via Compass, the app seeks to visualize that data in order for the CM to review so that they can adjust the activities for the student and compose reports for the stakeholders. You can learn more about it at the project’s source of truth

(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 Case Manager View - A web app with a browser-first view, for the setup of the Caseload:
      • Students and their IEPs. (The students are unique to the Case Manager for that school year)
      • Para-educators the Case Manager assigns to data collection for a student on the Caseload (Some Paras assist more than one CM)
    • Group 2: The Para-educator View - A web app with a mobile-first view, for the Para to collect data
    • 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 on the tail end of the design phase, and the Design Team and Project Management teams are deciding what components are needed and how the app should look and flow.

Current Development Phase

The MVP (Minimum Viable Product) for the app is Group 1's work: the Case Manager Initial View and Group 2's work: The Para View for Data Collection. The Data Visualization view will inform how we set that up, but is not a necessary part of coding the MVP. Currently, we are writing up new issues in the GitHub Projects board for Compass, and self-assigning them. We are currently working on any components we are sure will be needed, and displaying them in the Case Manager Dashboard file as React Components. Though we are working on some Para View components, we have not yet integrated toggling to them from the Case Manager View.

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; without logging in with the right credentials, you will get Auth errors and may be redirected to the Sign-In Page.

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, Via Great Communication

Since this is an open-source project, we are all here voluntarily in our spare time, which can lead to a loss of communication between team members and persistence on tasks, both of which make things Less Fun. In order to alleviate pressure and still keep the work flowing, 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 be sure to:

  • Have 2-4 assignees working on each issue
  • Be aware of your commitments, don’t commit to too many things at once, and let the tech team know via the Slack Channel if you have to step back for a few days and allow others to step forward and get coding 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 issue is not resolved, so long as 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. (You can simply communicate what your future plans are)
  • Feel free to create new issues for fixes if your group PR has already been submitted, or push those fixes up to the same branch if the PR is still open/not reviewed.
  • Have teammates communicate what everyone plans on doing before the next meetup, especially before any meetings To prevent a bottleneck or duplicating 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 comments, open it up to the tech group on the Tech channel. We’re all here to contribute and this may give someone the chance to help that they were hoping for.
  • You don’t HAVE to let other engineers fix your code or implement your ideas, but be realistic about your energy and time - your contributions are valuable and you will have more chances to do cool things later if you can’t fix something at this time.
  • You may find your solution creates non-breaking bugs while still solving the issue. So long as your PR passes the tests, PLEASE submit the PR, with a comment about the bug. Then you can create a bug issue, 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
  • 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 Code Review to get the branch, and then you can git push origin branchname with your fixes and they should be added to the PR.
  • 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 "[ENG]" in their names, and/or the green "engineering" label. You can add issues to the "Todo" list as they become obvious from meetings and discussions of the app. For now, we are adding issues for the MVP (The Case Manager View), but you are welcome to add issues for the Para View and Data Visualization flow to the "Blocked/On Hold" list.

  • 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
  • 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 try to have 2-3 people per issue and pair program/otherwise work 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 will be building are going to display in the components in the "pages" folder. In Next.js, the pages folder creates the URLs to which users navigate. Most of the Case Manager View components or navigation to them will render via the "pages/cmDashboard.tsx" file
    • 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. For the MVP (CM View), these will be in the "components/case_manager" 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).
      • Routers
        • The asynchronous database queries are written here in Kysely. These files will be where you write your back-end functions.
        • 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.
    • 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 The CSS for this app is still under development, but whatever you'd like to work with, be it a global CSS stylesheet, inline CSS, or tailwindCSS, go for it! Simply understand that less is better right now, since the UX/UI Team is coming up with their solutions and things are in flux, so we are concentrating on the build rather than the styling at this time.
  • Comments: Please use comments to clarify EITHER: what your code is intended to do (though this can be solved with good, clear naming choices), or if there is future work planned and it's not obvious that's the case.

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 merge 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, 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.

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]>"

You can find out more about it 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
  • Submit the Pull Request
  • Assign 1-2 team members to review the PR
  • Follow up on 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)

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

(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

You can use any kind of CSS for now, whether it be inline, tailwindCSS, or using the global CSS stylesheets in the "src/styles" folder. Simply try to stick with the UX/UI team's current styles as much as possible and don't do too much flexbox or grid work that we might have to undo later. Most of the styling will take place later after we have built most of the components and the UX/UI Team has come to an agreement on the optimal mix of styling for the elements.

(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) on the same date for that student 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."

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.

Trial: A single occurrence of a Benchmark 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 Benchmarks via trials.

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

(back to top)

Clone this wiki locally