-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: adding notes for developers on prod deploy, licensing, and mino…
…r corrections (#198) I want to preface this by saying that I'm planning on rescoping #187 and adding a follow-up issue. In this PR, I address parts of the original spirit of #187: * documenting the prod CD pipeline * updating relevant portions of the docs to be *more correct* * adding a licensing/attribution section * adds TOC I want to move the discussion around Next.js, as well as the general design choices, to a project design document not unlike the one for [Creative Lab's website](https://github.com/UCLA-Creative-Labs/sunshine/blob/master/DESIGN_GUIDELINES.md). More in #202. closes #187.
- Loading branch information
Showing
1 changed file
with
86 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,9 +7,34 @@ | |
|
|
||
| Hey there! This repo contains all of the code for ACM @ UCLA's front-facing website, which you can view at [uclaacm.com](https://uclaacm.com) or at [acm.cs.ucla.edu](https://acm.cs.ucla.edu). You can find out more about our organization, the events we hold, and all the different committees within ACM! | ||
|
|
||
| Our website is built with [Next.js](https://nextjs.org/) on top of [React](https://reactjs.org), with a style and [design system](https://design.uclaacm.com) internally developed by our dev team and [ACM Design](https://design.uclaacm.com). The site is deployed on [Netlify](https://www.netlify.com/); we're grateful for their support in the open-source program. | ||
| Our website is built with [Next.js](https://nextjs.org/) on top of [React](https://reactjs.org), with a style and [design system](https://design.uclaacm.com) internally developed by our dev team and [ACM Design](https://design.uclaacm.com). The site is deployed on [Netlify](https://www.netlify.com/); we're grateful for their support in the open-source program. Under the hood, we use both [ESLint](https://eslint.org/) and [Stylelint](https://stylelint.io/) to lint our JS and CSS code respectively. | ||
|
|
||
| ## Development Setup | ||
| ## Quick Table of Contents | ||
|
|
||
| * [Notes for Developers](#notes-for-developers) | ||
| * [Design Guidelines](#design-guidelines) | ||
| * [Development Setup](#development-setup) | ||
| * [Contribution Workflow](#contribution-workflow) | ||
| * [Production Deploy](#production-deploy) | ||
| * [Notes on Previous Iterations](#notes-on-previous-iterations) | ||
| * [Licensing and Attribution](#licensing-and-attribution) | ||
|
|
||
| ## Notes for Developers | ||
|
|
||
| ### Design Guidelines | ||
|
|
||
| *Doc coming soon!* | ||
|
|
||
| Have questions about the overarching project of this website, like: | ||
|
|
||
| * what technologies do we use? | ||
| * what are our code writing styles? | ||
| * where should I add ___ file? | ||
| * what method would I do to make a ___? | ||
|
|
||
| Check out our project design doc for more information! | ||
|
|
||
| ### Development Setup | ||
|
|
||
| We'll follow a very traditional [Node.js](https://nodejs.org) project setup. Before we start, make sure that you have the LTS version of Node (currently ~ `14.x`) and a copy of [`git`](https://git-scm.com/) on your computer. | ||
|
|
||
|
|
@@ -37,7 +62,7 @@ event - compiled successfully | |
|
|
||
| This should automatically open up a window in your browser with our website; if it doesn't, visit [http://localhost:3000](http://localhost:3000). | ||
|
|
||
| Note that `next dev` ships with Hot Module Reloading, so every time you modify a file, the app will automatically recompile and reload! | ||
| Note that `next dev` ships with ["Fast Refresh"](https://nextjs.org/docs/basic-features/fast-refresh) (their version of hot module reloading), so every time you modify a file, the app will automatically recompile and reload! | ||
|
|
||
| ### Contribution Workflow | ||
|
|
||
|
|
@@ -46,20 +71,75 @@ Want to make a change to the website? Great! Here are the steps: | |
| 1. Either make a new branch or a fork of this repository. `main` is a protected branch, **so you cannot push to it**. | ||
| 2. Follow the instructions in "Development Setup" above. If you're on a fork, replace the URL with the fork's URL; if you're on a different branch, check it out using `git checkout`. | ||
| 3. Make your changes! | ||
| 4. **Before you push**, make sure your app builds with `npm build`. If there are any errors, our CI/CD service will **reject your build**. | ||
| 4. **Before you push**, make sure your app builds with `npm run build`. If there are any errors, our CI/CD service will **reject your build**. | ||
| 5. Once you're ready, stage and commit your changes! | ||
| 6. Make a [pull request](https://github.com/uclaacm/website/pulls) with your changes, and let someone on the dev team know. | ||
| 7. If your code passes code review, we'll merge it into `main`. Congratulations! If you'd like, it's now safe to delete your branch/fork. | ||
|
|
||
| ### Production Deploy | ||
|
|
||
| TODO | ||
| We currently deploy our site on [Netlify](https://www.netlify.com/), which handles both our deploy previews and our production deploy. To use Netlify properly with [Next.js](https://nextjs.org/), we use Netlify's first-party [Essential Next.js](https://github.com/netlify/netlify-plugin-nextjs) plugin. Because Netlify typically only deploys static sites, this plugin allows us to use Next's SSR features, as well as other runtime behaviours like image optimization. | ||
|
|
||
| As a note, we've been running into some problems with `next/image` working properly - that's why some parts of the codebase stil use the `<img />` tag. It's likely that these problems have to do with a misconfiguration/misuse of the Netlify plugin, or a lack of feature parity surrounding runtime image optimization. | ||
|
|
||
| The CD pipeline is also mimicked in GitHub Actions. To ensure that your build passes production deploy, ensure that `npm run build` passes; you should get something like: | ||
|
|
||
| ### Notes on Previous Iterations | ||
| ```sh | ||
| $ npm run build | ||
|
|
||
| > [email protected] build /Users/matt/code/acm-website | ||
| > next build | ||
|
|
||
| info - Using webpack 5. Reason: Enabled by default https://nextjs.org/docs/messages/webpack5 | ||
| info - Checking validity of types | ||
| info - Creating an optimized production build | ||
| warn - Compiled with warnings | ||
| info - Collecting page data | ||
| info - Generating static pages (8/8) | ||
| info - Finalizing page optimization | ||
|
|
||
| Page Size First Load JS | ||
| ┌ ○ / 1.96 kB 102 kB | ||
| ├ /_app 0 B 74.5 kB | ||
| ├ ○ /404 1.36 kB 75.8 kB | ||
| ├ ○ /about 2.35 kB 102 kB | ||
| ├ ○ /committees 2.7 kB 103 kB | ||
| ├ ○ /events 579 B 84.6 kB | ||
| ├ ○ /sponsors 1.28 kB 101 kB | ||
| └ ○ /techgala 841 B 101 kB | ||
| + First Load JS shared by all 74.5 kB | ||
| ├ chunks/framework.2191d1.js 42.4 kB | ||
| ├ chunks/main.d8370c.js 20.3 kB | ||
| ├ chunks/pages/_app.bdb986.js 11 kB | ||
| ├ chunks/webpack.715970.js 804 B | ||
| └ css/15f1248eb2a7bef58d0d.css 6.13 kB | ||
|
|
||
| λ (Lambda) server-side renders at runtime (uses getInitialProps or getServerSideProps) | ||
| ○ (Static) automatically rendered as static HTML (uses no initial props) | ||
| ● (SSG) automatically generated as static HTML + JSON (uses getStaticProps) | ||
| (ISR) incremental static regeneration (uses revalidate in getStaticProps) | ||
| ``` | ||
|
|
||
| Outside of image optimization, the rest of our site is SSG'd by Next. In other words, after build-time, you should expect a fully-functional site (barring image serving). | ||
|
|
||
| ## Notes on Previous Iterations | ||
|
|
||
| From (some time) to 2019, this website had a more involved build system, still using React but also managing our webpack configuration, ESLint, containerization with Docker, and deploying on Heroku. | ||
|
|
||
| In mid-2020, we made two larger changes: | ||
|
|
||
| * we followed [ACM Design's](https://design.uclaacm.com) new **Branding 3.0** design system, reworking the visual language of the site | ||
| * we moved away from a custom webpack configuration and containerization deployed on Heroku to using [Create React App](https://create-react-app.dev/) deployed on Netlify, with the main goal of reducing development burden and taking advantage of static-site deployers | ||
|
|
||
| In mid-2021, we made another set of changes surrounding performance and robustness: | ||
|
|
||
| * we swapped out Create React App for [Next.js](https://nextjs.org/), with the goal of using the hybrid SSG + SSR/ISR model to deliver better performance and SEO-friendly pages | ||
| * some more stuff coming soon :) | ||
|
|
||
| ## Licensing and Attribution | ||
|
|
||
| Unlike the majority of ACM at UCLA's projects, this website is under the slightly-less-permissive [Mozilla Public License 2.0 (MPL 2.0)](https://github.com/uclaacm/website/blob/main/LICENSE). You can find the [public official copy on the Mozilla website](https://www.mozilla.org/en-US/MPL/2.0/), as well as [an FAQ on the license](https://www.mozilla.org/en-US/MPL/2.0/FAQ/). We echo a sentiment shared on the FAQ: | ||
|
|
||
| > Please note that, while this FAQ is intended to be accurate and helpful, *it is not the license*, and may not cover important issues that affect you and your specific situation. As a result, reading the FAQ should not serve as a substitute for reading the license itself, or for seeking legal advice from a lawyer. | ||
| We'd love to hear from you if this repository was helpful in any way (especially if it inspires your own work)! Send us an email at [[email protected]](mailto:[email protected]) - I promise we don't bite! | ||