Feat/no ref/sponsors workshops docs

.github/workflows/production_check.yml

@@ -1,21 +1,25 @@
 name: Production test
 on:
-  pull_request: # run only on created pull request on main
-    branches: 
+  pull_request: # run on pull requests into the deployed branch (dev) and main
+    branches:
+      - dev
       - main
-      
+
 jobs:
   build:
-    name: run lint and tests
+    name: run lint and production build
     runs-on: ubuntu-latest
     steps:
-      - name: check out code 
-        uses: actions/checkout@v2
+      - name: check out code
+        uses: actions/checkout@v4
       - name: setup node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
       - name: install dependencies
-        run: npm install
+        run: npm ci
       - name: running lint
         run: npm run lint
-      - name: run eslint
-        run: npm run alltests
+      - name: production build
+        run: npm run build

DEPLOYMENT.md

@@ -0,0 +1,80 @@
+# Deployment & Testing
+
+## Where the site is hosted
+
+| Domain                                         | Points to                     | What it serves                                           |
+| ---------------------------------------------- | ----------------------------- | -------------------------------------------------------------- |
+| [quantsoc.org](https://quantsoc.org)           | `dev.website-dk1.pages.dev`   | **The live site** - the latest build of the `dev` branch |
+| [staging.quantsoc.org](https://staging.quantsoc.org) | `dev.website-dk1.pages.dev` | The same as quantsoc.org - **not** a separate staging site |
+| [dev.quantsoc.org](https://dev.quantsoc.org)   | `website-dk1.pages.dev`       | An old, outdated build (Cloudflare's "production" deployment) |
+| [mtg.quantsoc.org](https://mtg.quantsoc.org)   |                               | The Mock Trading Game - a separate app, not in this repo |
+
+The live site at quantsoc.org is a build (`npm run build`) of the **`dev` branch**. The `main` branch is 100s of commits out of date and is not what's live.
+
+> ⚠️ **Pushing or merging to `dev` deploys straight to the live site.**
+
+**Firebase Hosting:** The repo uses Firebase only for the Firestore database. Do **not** run `firebase init` or `firebase deploy`, at best it does nothing, at worst it creates a second, copy of the site.
+
+### Cloudflare Pages setup
+
+Found in the Cloudflare dashboard -> Compute -> Workers & Pages -> the project -> Settings.
+
+| Setting                | Value                                           |
+| ---------------------- | ----------------------------------------------- |
+| Project name           | `quantsoc-dev` (to confirm, see below)          |
+| Pages address          | `website-dk1.pages.dev`                         |
+| Automatic deployments  | Enabled (every push to GitHub triggers a build) |
+| Production branch      | `main` (see below)                              |
+| Build command          | `npm run build`                                 |
+| Build output directory | `dist`                                          |
+| Root directory         | (empty - the repo root)                         |
+| Build comments         | Enabled (preview links are posted on PRs)       |
+
+### How `dev` ends up live
+
+Cloudflare treats `main` as the production branch, and every other branch gets its own preview deployment at `<branch>.website-dk1.pages.dev`. quantsoc.org is not attached to the production deployment. Instead, its DNS record points at the `dev` branch's preview address, `dev.website-dk1.pages.dev`, which always serves the newest build of `dev`. So:
+
+- **Pushing to `dev`** updates `quantsoc.org` (and `staging.quantsoc.org`).
+- **Pushing to `main`** only updates `website-dk1.pages.dev` and `dev.quantsoc.org`. It does not affect the live site.
+- **Pushing any other branch** creates a preview at `<branch>.website-dk1.pages.dev`. Branch names are shortened and made lowercase in the address, and `/` becomes `-`.
+
+## Testing a change safely
+
+There is no automated test suite, so testing means building the site and looking at it.
+
+1. **Work on a branch**, never directly on `dev`:
+   ```bash
+   git checkout dev && git pull
+   git checkout -b feat/no-ref/short-description
+   ```
+2. **Develop** with `npm run start` (http://localhost:5173).
+3. **Check the production build**, because this is what actually gets deployed:
+   ```bash
+   npm run build     # must finish with no errors
+   npm run preview   # serves the build at http://localhost:4173
+   ```
+   Click through every page you touched, and also check:
+   - a narrow window (or your browser's device toolbar) for mobile layout
+   - every link and button you added
+   - the browser console for errors
+4. **Lint the files you changed**: `npx eslint path/to/File.jsx`.
+5. **Push the branch and open a pull request into `dev`.** The GitHub Actions check (`.github/workflows/production_check.yml`) runs lint and a production build on every PR into `dev`. Cloudflare Pages will also build the branch and comment a **preview URL** on the PR (staging.quantsoc.org can't be used for this - it shows the live site). That URL is a real deployment that is *not* the live site - the best place for a final check, and to share with the exec.
+6. **Merge into `dev`** once someone else has reviewed it. This is the step that goes live.
+
+## Deploying
+
+**Merging the PR into `dev` is the deployment** - Cloudflare builds and publishes it automatically. Watch the build in the Cloudflare dashboard (the project -> Deployments), then check https://quantsoc.org. You may need a hard refresh (Cmd/Ctrl + Shift + R) to see changes.
+
+There is no need to build or upload anything by hand.
+
+## Rolling back
+
+Revert the bad commit on `dev` and push:
+
+```bash
+git checkout dev && git pull
+git revert <sha>
+git push
+```
+
+Cloudflare rebuilds the live site within a few minutes. You can find the `<sha>` of the bad commit with `git log`, or in the Cloudflare dashboard -> the project -> Deployments.

README.md

@@ -8,36 +8,76 @@
 
 [![Production test](https://github.com/QuantSoc/website/actions/workflows/production_check.yml/badge.svg)](https://github.com/QuantSoc/website/actions/workflows/production_check.yml)
 
-This repo contains the source code for the frontend of the main website of the 📈UNSW Quantitative Finance and Trading Society (Quantsoc), powered by [ReactJs](https://reactjs.org/).
+This repo contains the source code for the main website of the 📈 UNSW Quantitative Finance and Trading Society (QuantSoc), live at **[quantsoc.org](https://quantsoc.org)**.
 
+It is a single-page [React](https://reactjs.org/) app built with [Vite](https://vitejs.dev/). Articles and job listings are read from a [Firebase Firestore](https://firebase.google.com/docs/firestore) database; everything else is static.
 
-<!-- ## Major packages (add this later perhaps) --> 
+**Deploying:** Read [DEPLOYMENT.md](DEPLOYMENT.md) first. The live site is built from the `dev` branch.
 
 ## Quick start
-Once you have  a rather recent version of `npm` installed on a (preferably) Unix based system, simply run: 
-```
-$ npm install
-$ npm run prepare
-```
-Then you may run a development setting via:
-```
-$ npm run start
-```
 
-## Tests and linting
-The cleansing process will run before each push, however, you can run the linting and test manually by doing: 
-```
-$ npm run lint
-$ npm run test
+You need [Node.js](https://nodejs.org/) 20 or newer (the dev container uses Node 20) and `npm`.
+
+```bash
+npm ci            # install the exact dependency versions from package-lock.json
+npm run prepare   # install the git hooks (husky) - only needed once per clone
+npm run start     # start the dev server at http://localhost:5173
 ```
 
-## Running in production
-To run a quick production build, simply do:
+The dev server reloads automatically when you save a file. Nothing you do locally affects the live website.
+
+**Note:** the site reads articles and job listings from the **real** Firestore database, even locally. The site only ever *reads* data, so this is safe, but anything you see in those sections is live data.
+
+## Scripts
+
+| Command           | What it does                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `npm run start`   | Dev server at http://localhost:5173                                                   |
+| `npm run build`   | Production build into `dist/`                                                         |
+| `npm run preview` | Serves the `dist/` build at http://localhost:4173 - use this to check a build locally |
+| `npm run lint`    | Runs ESLint                                                                           |
+| `npm run prepare` | Installs the husky git hooks                                                          |
+
+There is currently **no automated test suite** (there is no `npm run test`). Testing is done by building and checking the site by hand - see [DEPLOYMENT.md](DEPLOYMENT.md#testing-a-change-safely).
+
+## Project structure
+
 ```
-$ npm run build
-$ npm run serve
+src/
+├── App.jsx               # Routes: /, /articles, /resources, /contact, /mathsprint
+├── firebase.config.js    # Firebase/Firestore client setup (see below)
+├── assets/               # Images; sponsor logos live in assets/sponsor-logos/
+├── components/           # Components shared by more than one page (NavBar, Footer, ...)
+├── routes/               # One folder per page. Components used by only one page live in that page's folder
+├── hooks/
+└── styles/               # Global .less styles and colour constants (styles/constants.less)
+legacy/                   # Old Python backend - not used by the current site
 ```
-## Resources 
-For conventions, module structure, advanced configuration or cooler stuff, check out the [wiki](https://github.com/QuantSoc/website/wiki) page.
 
-To learn React, check out the [React documentation](https://reactjs.org/).
+Import aliases (`components/...`, `routes/...`, `assets/...`, `styles/...`, `hooks/...`) are defined in `vite.config.js`.
+
+## Common tasks
+
+### Updating sponsors
+
+Sponsors are hard-coded in `src/routes/LandingPage/SponsorshipSection/SponsorshipSection.jsx`.
+
+1. Put the logo in `src/assets/sponsor-logos/`. Prefer an SVG, otherwise a PNG with a transparent background. The site has a **white background**, so use a dark/coloured version of the logo, not a white one.
+2. Import the logo at the top of `SponsorshipSection.jsx`.
+3. Add a `<Sponsor logoSrc={...} sponsorLink="https://..." />` line under the right tier (`principal` or `major`). Logos appear in the order they are listed.
+4. Run `npm run start` and check the Sponsors section on both desktop and a narrow (mobile) window.
+
+### Workshop materials
+
+Workshop slides and code are published in the [QuantSoc/workshop-materials](https://github.com/QuantSoc/workshop-materials) repo.
+
+### Updating Jobs Listings & Articles
+
+All the Job Listings are stored in the [Firebase Firestore](https://firebase.google.com/docs/firestore) database. Simply log into Firebase Hosting using quantsoc email OAuth, and then end it manually from there.
+
+## Firebase
+
+`src/firebase.config.js` connects the site to the `quantsoc-website-admin` Firebase project. It is only used to **read** the `articles` and `jobs` Firestore collections. The site is **not** hosted on Firebase (see [DEPLOYMENT.md](DEPLOYMENT.md)).
+
+The API key in that file is a public client identifier, not a secret (every visitor's browser downloads it). What actually protects the data is the project's Firestore security rules, which are managed in the Firebase console. They should allow public reads of `articles` and `jobs` only, and no public writes.
+

src/components/Footer/Footer.jsx

@@ -45,8 +45,13 @@ const Footer = () => {
                 </a>
               </li>
               <li>
-                <a className="nav-link" href="/admin">
-                  Board Login
+                <a
+                  className="nav-link"
+                  href="https://github.com/QuantSoc/workshop-materials"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  Workshop Materials
                 </a>
               </li>
             </ul>