/distributeaid.org

Distribute Aid's landing site!

Primary LanguageTypeScriptGNU Affero General Public License v3.0AGPL-3.0

DA Landing Site 2.0

CodeSee: View Architecture Diagram Open in Gitpod

Distribute Aid's landing site, where we get to tell the world who the heck we are and what the hell we're doing!

The main goals of this project are to:

  1. Create a landing site that introduces Distribute Aid, highlights our projects & services, publicly documents our impact, communicates upcoming plans to our network, highlights how to join / support us, and of course credits the many people who have contributed over the years.

  2. Make it easy for any Distribute Aid volunteer to manage content and publish changes to the site directly. This includes all text & images, but also data that powers components, pages & site structure, and some site metadata.

  3. Provide engaging pathways for design & dev volunteers to directly collaborate with the rest of the team, without holding them back. Our whole team will be contributing well structured content, which helps clarify what's needed without a ton of meetings. Use your favorite tools to make it shine.

Quick Links

Key Documents

Development Process

Code of Conduct

First, please read our code of conduct.

Issue Tracking

Development tasks are managed in the github issues for this repository. The issues themselves are fairly light on detail in favor of a simple description of scope (i.e. the conditions for the task being considered "done"). Most tasks will be driven by content requirements, so please coordinate with the requesting content creator for context, sample content, and additional details.

Issues tagged front end will also be tagged with:

  • needs sample content - A content creator needs to create sample content to show what information will be presented.
  • needs UI mock - A designer needs to create a UI mock of the component.
  • has content & UI mock - The task is ready for development!

When you begin working on an issue, please self-assign or comment on it indicating you're beginning work to avoid duplicate effort.

Pull Requests

When you're ready to submit your code, open a pull request with "Closes #X" to link the relavant issue. When your PR is approved by at least one maintainer it is ready to submit.

It's easy for the intention of code review comments to be unclear or get misinterpreted. To help with communication, reviewers are encouraged to use conventional comments and explicitly indicate that comments are (blocking), where the discussion must be resolved for PR to be merged, or (non-blocking) where resolving the discussion is optional for the implementer.

We highly recommend you create a CodeSee account, free for open source development. We use their data-flow recordings and codebase maps tool during our development and review processes to help make it easy to understand your changes or any problems you might run into along the way.

Approval and merging

Reviewers should grant approval if they do not feel additional review is necessary before merging. This does not necessarily mean no more changes are required before merging, but that any further changes are expected to be minor enough to not require review.

If the pull request does not require additional changes, the reviewer should merge it immediately after approving. Otherwise, the pull request author should merge (if able) once they have addressed all comments marked (blocking) or nit. Contributors are encouraged to at least reply to (non-blocking) and (if-minor) comments if they do not address them with code changes.

Dev Setup

Remote development:

Open in Gitpod

Gitpod allows us to pair on the cloud, as well as have an automatic setup with .gitpod.yml and get up and running right away.

Pressing the "Open in Gitpod" button will start up an VSCode-based instance in the cloud allowing you to be up and running with the codebase. You'll need to sign in with GitHub.

Note: When choosing VS Code desktop with Gitpod always be sure to select Linux from the dropdown as the operating system when prompted.

Locally

Install system dependencies:

  • Node v16
  • Yarn v1.22.5

Install project dependencies:

  • yarn

Run the dev server:

  • yarn dev

Finally, checkout the local site & GraphQL sandbox at:

Dev Notes

Crucial Commands

yarn dev

Run the project locally with live reload in development mode.

yarn build

Run a production build into ./public. The result is ready to be put on any static hosting you prefer.

yarn serve

Spin up a production-ready server with the site. Don't forget to build your page beforehand.

yarn clean

Remove cached data from Gatsby. A good first step if you believe you are running into issues caused by incorrect or outdated cached data.

Running the unit tests

yarn test

Running the end to end tests

First start the application locally with yarn dev. Then run yarn test:e2e.

Component development with Storybook

Storybook is a frontend workshop for building UI components and pages in isolation.

The documentation site has extensive guides and tutorials.

The page What's a Story is a must read. In short, each story describes a specific usage of a component, rendered in isolation within the Storybook UI. Controls and knobs can be used to change the component properties dynamically.

Components can have an arbitrary number of stories, gathered in files ending with .stories.tsx next to the component source file.

First run a production build with yarn build. Then run yarn storybook. This will start a server at the following address:

http://localhost:6006/

Where To Put Things

React src/ folder layout inspired by this blog post but can be changed up as desired.

Content management system

We use Forestry to manage our content. Forestry is a "git-based CMS", which means that all the content is stored inside this repo.

Visit the .forestry directory to view the configuration for our site, templates, and data files.

All the content is stored inside the content directory.

How do I edit content?

There are 3 ways to do edit content:

  • make a pull request through GitHub's UI
  • clone this repository and create a pull request
  • make changes in Forestry's UI (you'll need a Forestry account)

Deployment & Production

TODO

Content Creation

TODO

Technologies Used

Our Content "Supply Chain"

The Distribute Aid Landing Site is a static TypeScript website generated by GatsbyJS with content from the Forestry git-based headless CMS.

Content Management

General Tools

Build Tools

Front End

Production

Previous Work & Credits

Initial commit bootstrapped off of Contentful Gatsby Starter Blog which is MIT licensed.

The original DA Landing Site project can be found at https://gitlab.com/distribute-aid/landing. <3