Distribute Aid's landing site provides general information about our org, specific information about our projects / operations, and public access to the materials and tools we have developed. The main goals of this project are to:
-
Introduce Distribute Aid, the work we do, our impact to date, and the many people who have contributed over the years.
-
Make it easy for our non-dev volunteers to directly manage content and publish changes to the site.
-
Share relevant knowledge / data / tools that inspire visitors to take action in support of DA, our network, and grassroots aid groups in general.
Quick Links
- Production Site - https://distributeaid.org
- Github Repo - https://github.com/distributeaid/distributeaid.org
- ** Forestry CMS - https://app.forestry.io/sites/0pvklfck1gkdpg/#/
- ** Netlify Admin - https://app.netlify.com/sites/da-landing-2/overview
** require an account to access, please tag @jtfairbank in a comment if you need one
First, please read our code of conduct.
We use Github issues to manage development tasks 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. We strive to include an issue-specific CodeSee Map to highlight relevant files and folders.
When you begin working on an issue, please self-assign or comment on it indicating you're beginning work to avoid duplicate effort.
Issues with triage labels are still being finalized and are not ready for work.
When you're ready to submit your code, open a pull request with "Closes #X" in
the description to link the relevant issue. Our automated checks will run,
and then your PR will be reviewed by a maintainer. Once any pending issues are
resolved, the maintainer will merge it into our production branch, saga.
We recommend creating a "draft" pull request while you are still working on the issue. This allows you to ask maintainers for help / feedback during the dev process, and allows other contributors to see what you are working on for inspiration and to prevent duplicate efforts. You can make a draft pull request by following steps:
- Create a new branch to work on and make at least 1 commit (ex: add your name to the
/CONTRIBUTORS.mdfile). - Push the new branch and go to pull request page on Github. Accept the prompt that appears at the top of the page asking if you want to create a new pull request.
- Create the pull request like normal. Before submitting it, click the dropdown arrown on the "Create Pull Request" submit button and select "Create Draft" instead.
- You can now share your code and collaborate with other contributors / maintainers through the draft pull request. The draft pull request will automatically include any new commits pushed to your branch, just like a normal pull request.
- Once you've finished working on the issue, click the "ready for review" button on the pull request page and the "draft" status will be removed and a maintainer can begin the review phase.
DA aims to create a welcoming and encouraging environment for our contributors. 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.
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. Otherwise, the pull request author should address 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. After addressing the comments, the pull request author should tag the reviewer in a comment to indicate they are ready for a final review.
Pressing the "Open in Gitpod" button will start up a VSCode instance in the cloud, getting you up and running easily / quickly. You can share this instance with other contributors to pair remotely. Gitpod uses the .gitpod.yml settings to automatically configure your dev environment. 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.
Note: Your Gitpod instance will expire after you stop using it. To ensure your code is saved, you MUST create a branch, commit code changes, and push the branch up to Github.
Troubleshooting: Sometimes Gitpod runs into trouble when configuring the dev environment. If you run into problems, double check the different terminals to ensure that the
yarn installandnpx playwright install-depssetup commands completed successfully, the dev server is running, and the storybook server is running.
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:
yarn dev
Run the project locally with live reload in development mode.
Live reload works when changing files in /src, but if you are changing
/gatsby-node.js or files in /gatsby you will have to restart the dev server
and possibly run a yarn clean to have them take effect. That's because these
files control Gatsby's build process which is run once when starting the server,
as opposed to /src files which control the site's UI.
yarn clean
Remove data and build artifacts from Gatsby's cache.
We recommend doing this whenever you change branches or think you may be running
into issues caused by incorrect / outdated cached data. You may also need to run
this between builds if you are changing /gatsby-node.js or files in /gatsby.
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 pretty
This is included in our pre-commit hook so all committed code is formatted the same.
yarn test
First start the local server with yarn dev.
Then run yarn test:e2e in another terminal.
yarn test:types
This is included in our pre-commit hook so all committed code is type safe.
Storybook is a frontend workshop for building UI components and pages in isolation. Components can have an arbitrary number of stories, gathered in files ending with .stories.tsx next to the component source file.
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.
First run the dev server with yarn dev. Then run yarn storybook in another termainal. This will start the Storybook server at the following address:
We recommend you create a CodeSee account, free for open source development. We use their 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.
Please see these CodeSee Maps for more comprehensive signposting:
Our react src/ folder layout was inspired by this blog post but can be changed up as desired.
Data sourcing & processing code used by /gatsby-node.js should go in /gatsby.
Content is committed to /content by Forestry, our CMS. You can also place images, pdfs, and other file-based content in /static, but it's usually more appropriate to add them through Forestry.
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.
There are 2 ways to edit content:
- edit files in the
/contentdirectory and make a pull request through github - make changes in Forestry's UI (requires an account, tag @jtfairbank in a comment if you need one)
Netlify auto-generates build previews when pull requests are submitted on Github
(including draft pull requests). You can access them by going to the relevant
PR and clicking the "details" link on the netlify/da-landing-2/deploy-preview
check. Note that all other checks have to pass for a build preview to be made.
Netlify also automatically deploys the production site from our saga branch.
Pushing commits or merging pull requests into saga will trigger the deploy
after all checks are passed. If the checks or build process fail, Netlify will
continue to serve the existing version of the site.
Content Management
- Forestry - headless cms
General Tools
- Typescript - scripting language
- Yarn - package manager
- Prettier - code formatter (via the pretty-quick node module)
- Jest - unit test framework
- Playwright - end-to-end (E2E) test framework
- Storybook - component and page development workshop
- CodeSee - codebase maps and code visibility
Build Tools
- Gatsby.js - static site generator
Front End
- React.js - UI framework
- Tailwind.css - CSS framework
Production
- Netlify - build runner & hosting
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