MISC website

Getting Started

Prerequisities

• Node.js 20+
• pnpm

First-time Setup

1. Clone the repository and its content submodule:

git clone --recurse-submodules https://github.com/umisc/misc-astro.git

2. Navigate to the directory:

cd misc-astro

3. Run pnpm install:

pnpm install

4. Run pnpm dev to spin up your local development server:

pnpm dev

pnpm dev first applies D1 migrations and seeds the local database (pnpm db:setup:local), so a fresh clone gets a working local DB with no extra steps. If local state gets stale, reset it with:

pnpm db:reset:local

Making Changes

If you forgot to --recurse-submodules when cloning, run these two commands:

git submodule sync --recursive
git submodule update --init --recursive

To pull changes, run:

git pull --recurse-submodules
git submodule update --init --recursive

Adding an Event

Place the event image in content/images/events, then run this command from the root directory:

pnpm event:add

The command prompts for the event details, previews the finished record, and appends it to content/events.json. An ID is derived from the title and date, dates are converted to ISO format, image file path is checked to see if it exists. The script keeps events sorted.

Root Repository

To make changes to the root repository, the standard add, commit, push flow applies.

Make sure you are in the root directory.

git add .
git commit -m "feat: write a descriptive message of what you added"
git push

After you have pushed your branch to remote, follow the contribution workflow for further instructions.

Note: If you are on a branch (which you should be) which is not already on the remote repository, you may have to do git push -u origin feat/name-of-branch.

Content Submodule

1. To make changes to the content submodule, first navigate there:

cd content

2. Add your changes, commit, and push:

git add -A
git commit -m "feat: write a descriptive message of what you added"
git push

If git push does not work, you may have to do git push origin HEAD:main instead.

3. Wait for PR bot and then merge:

You can navigate back to the root directory with cd ...

Then, wait for the PR bot to auto-create a PR to bump the content submodule. After a few minutes you should see a PR in the repository's pull requests tab.

Once all checks pass, merge using "Squash and merge", not "Merge commit".

Without the PR bot

In the event that the PR bot does not work or it has been disabled, follow these instructions.

After step 6, add, commit, and push the updated submodule reference:

git add content
git commit -m "chore: bump content"
git push

Ensure that you are on a separate branch when pushing. Afterwards, make a PR and name it, chore: bump content submodule. Wait for checks to pass and then merge via "Squash and merge".

Using Astro

Read the Astro docs.

Cloudflare deployments

GitHub Actions deploys pushes to main to the misc-astro Cloudflare Worker. Pull requests from branches in this repository receive a non-production preview at a stable pr-<number> Workers preview URL.

Configure these GitHub Actions secrets in both the production and preview environments before enabling deployments:

• CLOUDFLARE_ACCOUNT_ID
• CLOUDFLARE_API_TOKEN

The API token needs permission to edit Workers Scripts. The custom production domain is deliberately not declared in wrangler.jsonc; add and validate the route only when traffic is ready to move away from the existing Vercel deployment.

Repository Rules

• useEffect and useLayoutEffect are banned in component files apart from in circumstances where you cannot refactor into a reusable hook that could conceivably be used by another component.
• pnpm check must pass before comitting. Try pnpm fix to fix some issues raised by pnpm check.
• Use Tailwind. Never create custom classes, ad-hoc css files, or inline stylesheets. Inline styles are acceptable in rare cases involving complex animation or maniupulation.
• Extensions to the tailwind theme need to be treated with great care. Clarify your intent and consider separately.
• For more complicated animations, use motion. Do not change animation libraries without refactoring all existing code to use them.
• Follow the design system. Avoid creating ad-hoc colours, spacing, border-radius, text sizes, buttons, and components that duplicate what already exists.
• Where new styles or designs are required, this must be treated separately as a change to the design system rather than an ad-hoc addition. This is an expansion of scope—intent must be clarified and treated with care. You can view the design system at /design-system.
• When you create new components, always check if an existing official shadcn component already exists. Please add these using the CLI (not copying the code!) and customise to suit the design system when they are available.
• Do not add icon packs or custom icons when the icon is available in phosphor icons.
• Content that should not be publicly accessible indefinitely must live in the content submodule. This repository is public, even deleted information and files will remain accessible.
• Use Typescript. Do not make Typescript any less strict. Use of any is banned. Use of as, !, and unknown must be heavily restricted and commented, explaining why you know more than the Typescript compiler. Where you need typed access to external data, it should be either:
  • Come typed through an SDK.
  • Be an Astro content collection.
  • Validated at runtime using Zod.

Contribution Workflow

1. Create or choose an issue for the work.
2. Create a branch from the latest main. Use <type>/<issue-number>-<short-description>, for example feat/123-name-of-branch or fix/456-name-of-branch.
3. Make and test your changes. Run pnpm check before committing.
4. Write commits using Conventional Commits: <type>(optional-scope): <description>, for example feat: add ctf guide. Common types include feat, fix, docs, refactor, test, and chore.
5. Push your branch and open a pull request into main.
6. Link the pull request to its issue using Closes #123, describe the changes and testing, then request review.
   1. When merging, prefer a fast-forward merge. This means:
   2. Rebase your branch on main
   3. Push your branch to GitHub and ensure it has an open PR with CI passing
   4. Run git checkout main then git merge feat/123-my-branch. This should perform a fast-forward merge. Run git push, GitHub will permit the push since the commits have been approved via the PR.

main is protected: do not commit unapproved commits push directly to it. All commits must be made on a branch and approved through a pull request before moving to main.