Onboarding
The architecture of our app is split up as separate web components. All the code lives in the Github repository source folder. Within that, we have a components folder for all the components the central control unit manages. For each custom component (e.g. timer), they have their own component folder containing the main and helper (if applicable) JS files and css for styling.
- Finish: Displays the number of pomodoros and breaks the user completed in a 24h period.
- Info: Informational display about how to use the application.
- Settings: Sliding display with input fields, dropdown menus, and sliders to customize the user experience.
- Timer: Controls the pomodoro timer.
- Toggle: Custom type of switch that turns a mode on or off.
- Sound: Controls the sound played when work time is complete, with adjustable volume and source controls.
- Tab: The browser tab which displays information about the mode and time remaining
- Control: The central control unit that listens to events fired by individual components and sets their functions. It switches between modes on the timer, deals with settings changes, and utilizes local storage to save and use stashed information.
- Resize: Allows for resizing of the components according to the window resize and tone for mobile users.
- Storage: Local/browser storage saves settings, the number of pomodoros, the number of short and long breaks, and interrupted work sessions for the day.
There is also a testing folder that contains all Cypress and Jest tests. We chose to use custom web components via shadowDOM to limit the visibility of each component and to have control handle the communication between each. We also use custom events wherein each component sends up a flag notifying control of a change that occurred.
After the developer writes their code and pushes it to their personal branch, the linter and any Jest and Cypress tests automatically run. After the tests complete, the developer can initiate a Pull Request and assign reviewers, linked Issues, milestones, and change the label to “PR: Needs Review”. After being reviewed by at least two other team members, if their code needs edits, the reviewer adds comments and changes the label to “PR: Reviewed with comments” and the developer would fix their code and go through the pipeline again. If no edits are needed, the reviewer changes the label to “PR: Ready to Merge”, then the developer or the reviewer can merge the code to Main. In the meantime, JSDocs automatically generates documentation for their commented JavaScript (e.g. function headers) after merging to Main.
Note: JSDocs and PR: Ready to Merge are flipped in our process
All documentation now exists in the Wiki.
On pushing to the project repository, Github automatically triggers actions of running the linter (eslint for Javascript files, stylelint for css files, and htmlhint for html files), code inspecting tools and unit tests. Per the coding standard, developers’ code must pass all linting tests unit tests in order to merge.
The linter is an automated checking tool that analyzes code for bugs and stylistic errors. Our linter is designed to follow these style guidelines and the Google style guidelines.
After the linter automatically runs within the PR, you are able to see whether the linter passed or not for your code. Click detail to see the specifics of the linter results. For example:
In the image, the errors happen in file base.css. On the right are the line and character numbers that the errors occur, and on the left are the suggestions to fix the error
For efficiency purposes, you can run linter checks locally by running npm run lint_test on the terminal.
Upon pushing to the project’s repository, Github automatically runs Jest and Cypress unit tests to make sure that the code passes all unit tests.
An example of a Jest run:
If a specific test doesn’t pass, Jest notifies you of which test.
An example of a Cypress run: In this example, the code fails two tests ‘Audio plays successfully’ and ‘Test default value’. The test program shows the error happens at line 152 in ‘test-pomo-audio.js’
For a detailed explanation on Jest and Cypress tests, please refer to our testing guide.
- Jest is a universal JavaScript testing framework designed for React.JS, but is usable for any JS library or framework.
- When to use it: unit testing, non shadow-DOM components testing, function testing
Examples:
Importing & Calling Explicit Functions
Calling Functions via an Imported Object
How to run locally:
npm run jest_test: to run tests
npm run jest_coverage: to display Jest coverage
- Cypress is a testing framework designed to be used for front end testing.
- When to use it: when testing shadow DOM items, UI and unit testing
- For example: Event testing, CSS checks such as color and positioning, variable checks, function call checks
Examples:
Finding a component that is a shadow DOM
Calling functions
Comparing texts/labels
How to run:
Locally
Github
The Main branch is configured to not allow direct modifications. When adding code, developers should create/use a branch for their feature. This is to ensure that developers have the freedom to experiment with their code with no permanent repercussions to the main branch and so that the main branch remains functional to all users.
After completing an issue, developers should make a Pull Request (PR) to the main branch:
- Navigate to your branch that you are making the PR for
- Click Pull Request
- Fill in title and description for the PR, add any necessary labels, and submit
Clone the repository:
git clone https://github.com/ntrappe/cse110-w21-group33.git
Set up your own branch:
git branch my_name_branch
Switch to a branch:
git checkout my_name_branch
Confirming you switched branches
git branch -v
See if your branch is up-to-date
git status
Reset branch to most recent commit:
git reset --hard
Remove lingering files
git clean -f -d
See if your branch is up-to-date
git status
Merge another branch into yours
git pull origin other_branch
Pull in a file from another branch
git checkout other_branch path_to_file
When you’ve created files or made changes:
git add .
git commit -m "I updated ___"
Push to your branch
git push origin my_name_branch
Get remote changes into your current branch
git pull
Get all current branches
git fetch
Check what branches you have
git branch -av
git rebase -i [HEAD or starting commit]~[number of commits from that point]
// example: git rebase -i HEAD~6
// "pick" the top commit then "squash" the others
git push --force-with-lease
You can view the app here: https://cse110team33.netlify.app/
The traditional Pomodoro Technique consisted of sets. Each set was divided into 4 work sessions—called pomodoros—with the first 3 followed by a short break and the final work session followed by a long break. Cirillo, the creator, used 25 minute pomodoros, 5 minute short breaks, and 15 minute long breaks. If a work session is interrupted, that Pomodoro is considered “forfeited” and the user must restart it. However, our app allows our users flexibility in modifying the lengths of these intervals to match their work styles.
To use the app, get started by clicking Info at the top right for more information about the Pomodoro process. You can begin the timer by clicking Start, and Reset if you are unable to complete the current pomodoro cycle.
Click Settings at the top left to customize the pomodoro, including adjusting the work time, break time, switching between calm and dark mode, adjusting audio, and turning on and off accessibility.
Click Stats at the bottom right to view all your completed pomodoros and breaks for the day.