CONTRIBUTING.md

Contributing: Fridge Finder

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in the #frontend channel on Discord.

Table of Contents

1. Join the communication channels
2. Configure shell
3. Configure git
4. Configure development environment
5. Select a task
6. Create a feature branch
7. Create a commit
8. Update the feature branch for code review
9. Request a code review

Join the communication channels

You need permissions to the following accounts to contribute to the project.

• Trello for project management. Click this Trello invite link to join.
• Discord for developer communication. Click this Discord invite link to join.
• Figma for design blueprints
• GitHub for the frontend repository
• GitHub for the backend repository

1. Email fridgefinderapp@gmail.com regarding account invites. In that email please include:

• your discord account name
• your github account name
• whether you will be contributing to the frontend, backend, or both.

2. Complete the Volunteer Intake Form

Communicating with project maintainers requires Discord and Figma. Both have webapp versions. We recommend installing the desktop version of Discord and Figma because they offer significant performance and UI enhancements.

Configure shell

Contributing to the project requires a shell terminal. On Windows, we recommend using git-bash because it consumes minimal system resources.

Configure git

These settings are not requirements of the project. They are provided as a service for people who are new to git.

This configuration sets up VS Code 1.70 and above as your git editor, diff and merge tool. These commands can be run in any shell terminal.

git config --global user.name "full name. the name on your resume"
git config --global user.email "myemail@example.com"

git config --global core.autocrlf false
git config --global core.filemode false
git config --global core.editor "code --wait"

git config --global push.default current
git config --global pull.default matching
git config --global pull.ff only

git config --global pretty.all "format:%C(auto)%h %C(green)%<(15,trunc)%aN %C(reset)%<(80,trunc)%s %C(yellow)%<(30,trunc)%S %C(auto)%d"
git config --global pretty.summary "format:%C(auto)%h %C(green)%<(15,trunc)%aN %C(reset)%<(80,trunc)%s %C(auto)%d"

git config --global diff.guitool vscode
git config --global merge.guitool vscode

git config --global difftool.prompt false
git config --global mergetool.prompt false
git config --global mergetool.keepBackup false

git config --global difftool.vscode.cmd 'code --wait --diff "$LOCAL" "$REMOTE"'
git config --global mergetool.vscode.cmd 'code --wait --merge "$REMOTE" "$LOCAL" "$BASE" "$MERGED"'
git config --global mergetool.vscode.trustexitcode true

Run these commands only if you are using Windows Command or PowerShell as your shell terminal:

git config --global difftool.vscode.cmd "code --wait --diff $LOCAL $REMOTE"
git config --global mergetool.vscode.cmd "code --wait --merge $REMOTE $LOCAL $BASE $MERGED"

The following creates git aliases for the bash and zsh shells. Add these lines to your shell configuration file. Type code ~/.bashrc to open the bash shell configuration file. Type code ~/.zshrc to open the zsh configuration file.

# --- git
alias ga='   f() { git add $@; git --no-pager status --short; };f'
alias gaa='  git add --all; git --no-pager status --short'
alias gb='   git branch'
alias gc='   f() { git commit -m "$*"; };f'
alias gca='  git commit --amend -C HEAD'
alias gcam=' f() { git commit --amend -m "$*"; };f'
alias gcp='  f() { git cherry-pick --no-commit $@; git --no-pager status --short; };f'
alias gd='   git difftool --gui'
alias gdn='  git --no-pager diff --name-only'
alias gm='   git mergetool --gui'
alias gl='   git log --pretty=summary --use-mailmap'
alias gla='  git log --pretty=all     --use-mailmap --source --all'
alias gln='  git log --pretty=summary --name-status -n 5'
alias glf='  git --no-pager log --follow --oneline -- '
alias go='   git checkout'
alias gpop=' git stash pop'
alias gpush='git stash push'
alias gpls=' git --no-pager stash list'
alias gs='   git status --short; echo; git --no-pager log --pretty=summary -n 3'
alias gsls=' git status --porcelain | /usr/bin/cut -c4-'
alias gh='   git show'
alias ghn='  git --no-pager show --name-status'
alias gri='  git rebase --interactive --autosquash'
alias gra='  git rebase --abort'
alias grc='  git rebase --continue'
alias gr-d=' git fetch --prune && git rebase --interactive origin/dev'
alias gop='  git push origin -u'
alias gol='  git pull --ff-only'
alias gof='  f() { git fetch --prune $@; git gc --auto; };f'
alias clean='f() { find . -type d \( -name .git -o -name node_modules -o -name .next \) -prune -o -type f -name "*.orig" -print | xargs -I % rm %; git gc --aggressive; };f'

HISTIGNORE="$HISTIGNORE:gaa:gca:gm:gpop;gpush:gs:gra:grc:gr-d:gof:clean"

Configure development environment

Running the Fridge Finder webapp requires Node. The Fridge Finder webapp should be setup by following the instructions in the readme.

Select a task

We use Trello to keep track of tasks.

• Backlog : A list of tasks that cannot be started
• Todo : A list of tasks that can be started
• In Progress : Tasks currently being worked on
• Code Review : Tasks waiting for review
• Done : Completed tasks

You can pick any task from the Todo column that does not already have members. Once you begin working on a task, add yourself as a member, and move it to In Progress.

Create a feature branch

Create a feature branch for the task you are working on. Branch names must be in lowercase and in this format: cfm_<task number>_<initials>. The task number is in the task title [CFM_#]. The initials come from the name you use on your resume. For example, if Jean Paul starts work on [CFM_22], he would use the following commands to create a feature branch:

git fetch --prune                               # gof
git checkout origin/dev --no-track -b cfm_22_jp # go origin/dev --no-track -b cfm_22_jp

Create a commit

The commit message header must be in the format: <type>: <subject>

type is one of the following tags:

• feat : new feature for the user, not a new feature for build script
• fix : bug fix for the user, not a fix to a build script
• refactor : refactoring production code, eg. renaming a variable
• test : adding missing tests, refactoring tests; no production code change
• perf : performance improvements to production code
• style : formatting, missing semi colons, etc; no production code change
• asset : changing static assets. ie css files, images, etc
• doc : changes to the documentation
• ci : updating CD/CI pipeline; no local script changes
• chore : updating grunt tasks etc; no production code change
• revert : reverting a previously published commit

subject must abide by the following rules:

• subject must start with a capital letter
• subject must not end with a period
• subject must not exceed 70 characters

commit header examples:

• feat: Add hat wobble
• wip: Move commit-convention to docs

The complete details on commit messages can be found in the commit convention.

Update the feature branch for code review

While it is very useful to create multiple commits during development; for effective code management, every feature needs to be in its own commit. Follow these steps to create atomic commits and incorporate the latest changes from origin/dev before submitting your feature branch for review. The feature branch must include a demo of the feature as a single commit. Reach out on Discord if you need help with this process.

1. Ensure that all work complies with the review criteria

2. Ensure that all work is committed and the branch is clean

   • display changed files

   git status                        # gs

   • commit changes to the current branch

   git add --all                     # gaa
   git commit -m 'wip: Current work' # gc wip: Current work

3. Combine all the commits on the feature branch. To do this, count the number of commits, then reset the brach to HEAD~(commit count). For example, Jean Paul made 5 commits to his feature branch cfm_22_jp:

   f557166 Jean Paul       chore: Refactor code and delete extraneous files         (HEAD -> cfm_22_jp)
   e391cf1 Jean Paul       feat: Added FridgeMap Search to filter fridge pins
   7850ecf Jean Paul       feat: Added Fridge Pin SVG to FridgeMap component
   310f581 Jean Paul       feat: Add List view Map view toggle
   53d26af Jean Paul       feat: Created cfm_22 fridgeMap Component
   f5191df Hamaad Chughtai feat: Create FridgeDetailed component
   

   His would use the following commands to combine all his commits:

   git reset --soft @~5
   git commit -m 'feat: Create FridgeMap component' # gc feat: Create FridgeMap component

4. Fetch the most recent commits from origin

   git fetch origin --prune  # gof

5. Rebase the feature branch on top of origin/dev

   git rebase origin/dev     # gr-d

6. Resolve all merge conflicts.

   • to view every conflicting file

   git mergetool --gui       # gm

   • continue rebase

   git rebase --continue     # grc

7. Delete the merge backup files and optimize repository disk usage

   # clean
   find . -type d \( -name .git -o -name node_modules -o -name .next \) -prune -o -type f -name "*.orig" -print | xargs -I % rm % ; git gc --auto

8. Create and commit the demo page

   • add the demo page

   git add src/pages/demo/*  # ga src/pages/demo/*

   • commit changes to the current branch

   git commit -m 'wip: Demo' # gc wip: Demo

9. Push the feature branch and move the associated Trello card to 'Code Review'

   git push origin -uf       # gop -f

Request a code review

Post a review request in the #frontend channel on Discord. If this is your first contribution, include your time zone and availability in the request.

Once your feature branch has been merged into dev, it will automatically be deployed to the staging website