Skip to content

Latest commit

 

History

History
202 lines (143 loc) · 5.88 KB

CONTRIBUTING.md

File metadata and controls

202 lines (143 loc) · 5.88 KB
Raw

Contributing

Thanks for being willing to contribute!

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

Content Changes

Most content changes can be made without cloning the repository. Simply locate the file you wish to change in the GitHub UI, and click the little edit icon to make your change directly on the GitHub website.

If you need to make any other substantial changes, then follow the project setup steps below.

Translation contributions

Translations for blog posts are more than welcome, but I'm afraid I don't have the bandwidth to manage them within this repository. So if you'd like to translate content on my blog, simply translate the post and put it on your own blog. Then come here and add a link to the translation in the mdx file for the post you translated. It should look like this:

---
title: Some great post
... other stuff ...
translations:
  - language: Español
    link: https://example.com/your/translation/link/here
    author:
      name: Your name
      link: https://example.com/your/link/here
... more other stuff ...
---

The link can be your twitter, website, or LinkedIn.

The only requirement is that at the beginning of your translation, you explain that it is a translation of the original post and link back to the original post. For example:

This is a translation of the original post Some great post by Kent C. Dodds.

If you notice an error in an existing translation or if the link to the translation is not working, please try to reach out to the translator directly to get it fixed. The only thing we can do in this repo is remove the link. If you feel that's necessary, feel free to open a pull request to do that.

Thanks for helping to make my content more accessible!

Project setup

If you do need to set the project up locally yourself, feel free to follow these instructions:

System Requirements

Setup steps

First, fork the repo, then do this:

git clone <your-fork>
cd ./kentcdodds.com

# copy the .env.example to .env
#   everything's mocked out during development so you shouldn't need to
#   change any of these values unless you want to hit real environments.
cp .env.example .env

npm run setup

That should do everything for you... If it doesn't work, here's basically what it does, go ahead and try each of these commands one at a time:

npm install

# make sure you have docker installed
# The `-d` tells docker to run this in the background
docker compose up -d

# get the postgres DB initialized to match our prisma schema.
npx prisma migrate reset --force

# Run type checking, linting, and unit tests
npm run validate

# Prime the cache with the mock data
npm run prime-cache:mocks

# Run the E2E tests
npm run test:e2e:run

If that all worked without trouble, you should be able to start development with:

npm run dev

And open up http://localhost:3000 and rock!

Mocks

Everything's mocked locally so you should be able to work completely offline. The postgres DB runs in a docker container locally, but all third party endpoints are mocked out via MSW.

Caching

Because the mdx files are built on-demand and that take some time, we heavily cache them via redis (which is configured in the docker-compose.yml file). This means that if you need to work on content, you'll need a way to clear the cache. Only the admin can clear the cache, but locally, you can login as the admin. Luckily for you, the postgres DB is seeded with an admin account you can use.

So first, you need to login as [email protected]. Simply enter that in as the email address, and then check the logs for the magic link. Copy that into the URL and you should be logged in as the admin.

Now that you're an admin, you can go to any MDX-based page and add ?fresh to the end of the URL and it'll clear the cache for that MDX.

Running automated tests

We have two kinds of tests, unit and component tests with Jest and E2E tests with Cypress.

# run the unit and component tests with jest via:
npm run test

# run the Cypress tests in dev mode:
npm run test:e2e:dev

# run the Cypress tests in headless mode:
npm run test:e2e:run

Jest runs on changed files as part of the husky git commit hook. Cypress runs only on CI.

Running static tests (Formatting/Linting/Typing)

Everything's set up with TypeScript/Prettier/ESLint. These should all run on commit (only relevant files are checked). You can run them individually though if you want:

npm run format
npm run lint
npm run typecheck

These are all configured in the project to hopefully work with whatever editor plugins you have so it should work as you working as well.

Styles

We use Tailwind for our styles. That's all configured in the tailwind.config.js file. We use the jit feature. The source files are in styles and they build to the app/styles directory where our app picks them up from there.

Database

We've got PostgreSQL and Prisma set up. Learn about the schema and learn more about what commands you can run in ./prisma/schema.prisma.

One common command you might need to run is to re-seed the database:

npx prisma migrate reset --force

In addition to resetting your database to the latest schema, it'll also run the seed script which will populate the database with some example data.

Help needed

Please checkout the open issues

Also, please watch the repo and respond to questions/bug reports/feature requests! Thanks!