About Distribute Aid

Distribute Aid is a grassroots-to-grassroots humanitarian aid organization.

Founded in 2019, we coordinate relief shipments and manage logistics for disaster response efforts around the world. Our open-source tools and a committed team of volunteers allow us to deliver more aid for less money, while also minimizing waste and emissions.

Table of Contents

• About Distribute Aid
• About Project
• Technologies Used
• Getting started
  • Setup
  • Installation
  • Choosing an Issue
  • Branching & Workflow
  • Coding Conventions / Best Practices
  • Project Structure
  • Running Checks
  • Crafting Commit Messages
  • Crafting a Pull Request (PR)
  • Creating Issues
    • Sub Issues
• Reviewing Pull Requests
• Merging Branches

About the Project

This repository contains the scaffolding for DA's new website, powered by Nextjs, TypeScript & Strapi.

Technologies Used

• Nextjs - Frontendframework
• Typescript - scripting language
• Radix UI - component libary
• Tailwind.css CSS framework
• npm - package manager
• Prettier - code formatter (via the pretty-quick node module)
• ESLint - Linting
• Vercel - Production and deployment

🚀 Getting started with Gitpod

Gitpod provides a fully automated development environment for your Next.js project, and the development environment is set up with just a single click. Follow these steps to get started:

1. Click the Open in Gitpod button above. Note: you'll need to have an account on Gitpod before proceeding with the next steps (this requires a GitHub account).
2. Click the Continue button.
3. Relax, a development environment is being set up for you in the first terminal.
4. To access your workspace later, go to Gitpod Workspaces. Pin the next-website-v2 workspace to prevent auto-deletion after 14 days by clicking the three dots next to the workspace name and selecting "Pin".

Setup

This setup comes preconfigured with Nextjs, TypeScript, Tailwind, and Next's Incremental Static Regeneration

To run a Nextjs project you'll need to install or update these dependencies:

• Node.js 18.17 or later
• Node Version Manager - to update Node.js

Installation

Here are the steps to set up the project in your local dev environment:

1. Install Dependencies:

- yarn install

2.Then run the development server to launch your app:

yarn run dev

3.Open http://localhost:3000 with your browser to see the result. You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

Choosing an Issue

Choose an unassigned issue from the Issue's page on Github or see which issues are Ready for Work in the DA Project Board. Note: issues labeled Good first issue are ideal for newcomers. Once chosen, be sure to assign yourself to the issue and mark the issue as In Progress.

Branching & Workflows

We have a long-running branch (saga) and create short-lived branches to develop parts of the website. Our branch naming convention is type/issue#/condensed-issue-name. An example of a short-lived branch would be feat/365/about-us. Connect words using a "-" as branch names cannot include empty spaces. Always ensure you're working on a separate branch to avoid merge conflicts.

Coding Conventions / Best Practices

• Avoid using raw #hexadecimal values. View /src/stylesheets/ or tailwind.config.ts to see color value names.
• Use Radix UI's component library and use tailwind CSS for supplementary styling.

Project Structure

We are using a Next project structure.

/public/

Contains images and documents that are used in different pages or components.

/src/

Most of the files you may be working with live inside the /src/ folder.

/src/app/

Contains the main pages for routing, meaning /src/app/[foldername]/page.tsx would route to the /[foldername] page on the website.

/src/components/

Each page is made up of multiple components that will be imported onto that specific page.

Running checks

To check types:

yarn run check:types

To run the linter:

yarn run lint

Crafting commit messages

When crafting commit messages, group commits that are related to a particular topic. For example, if you're making commits related to the styling, only include files that are related to styling. This makes it easier to read through the commits and see the exact files that made changes to the styles. See Conventional Commits for more information.

A good commit message will ideally have the following attributes:

• Subject => A summary of what you did in the commit.
• Body => A detailed explanation of the commit.
• Proper commits make debugging easier in cases where we need to go through our git logs.

Crafting a Pull Request (PR)

• Include the purpose of the Pull Request and link the issue related to the PR (with the # sign)

• Consider providing an overview of why the work is taking place (with any relevant links). Don't assume familiarity with the history

• Be explicit about what feedback you want, if any: a quick pair of ** on the code, discussion on the technical approach, critique on design, a review copy

• Be explicit about when you want feedback, if the Pull Request is a work in progress, say so. Prefix the title of your PR with [WIP]

• @mention individuals that you specifically want to involve in the discussion and explain the help or input you need from them.

• assign the issue owner as a reviewer

Happy coding!!!

Creating Issues

On the Issues page on Github, click the green New Issue button or this New Issue Link.

• Add a descriptive title with an optional [type tag] such as [component] or [page]. In the description body summarize the issue.
• Add external links, such as to figma designs or external documentation, if applicable. If a figma design exists, be sure to add screenshots. Visual explanations go a long way towards making things super clear.
• Add parts of the codebase where changes would be made.
• Assign the issue to yourself or someone else, or leave for another person to pick it up.
• Add appropriate labels and types.
• Add the issue to the project DA Tech.

If the issue needs some precursor set up before someone can work on the issue (particularly for parents of sub issues) such as library installations and page or folder creations, then you must first set the issue as Triage until those appropriate changes are made and reviewed in a pull request. Otherwise, set the issue as Ready for Work.

Sub Issues

For larger issues that can be split up into separate independent parts. For example a new parent page with multiple children components. You can create a parent issue, with multiple child issues. See these slides on how to create sub issues.

Reviewing Pull Requests

When reviewing changes, first give praise for the work done. Leave a general summary of the changes needed to be made. Individual comments can be put to show specific instances or examples directly in the codebase. See Conventional Comments for more information.

A good comment will ideally have the following attributes:

• Label => Signifies what kind of comment is being left
• Subject => Main message of the comment
• Decorations (optional) => These are extra decorating labels for the comment. They are surrounded by parentheses and comma-separated.
• Discussion (optional) =>This contains supporting statements, context, reasoning, and anything else to help communicate the “why” and “next steps” for resolving the comment.

Labeling comments encourages collaboration and saves hours of undercommunication and misunderstandings.

Merging Branches

Use git rebase to resolve any merge conflicts between branches. Once the incoming branch is merged into saga, it is safe to delete.