diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 117 |
1 files changed, 106 insertions, 11 deletions
@@ -11,7 +11,9 @@ git clone https://github.com/Sycamost/lallans-wabsteid-astro.git \ && npm run dev ``` -## All you need to edit the website +## Contributing + +### All you need to edit the website * Has a text editor or IDE and can use it to edit text files. * Can write Markdown. (Beginners can learn in an afternoon by following the @@ -30,31 +32,49 @@ git clone https://github.com/Sycamost/lallans-wabsteid-astro.git \ * Can use [NPM](https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/) to install dependencies and run scripts. -## Writing a news post +### General guidance 1. If you haven't already, fork the repository, and clone your fork. -2. Copy and paste an existing news article in both English and Scots. You will +2. Make a suitably named branch on your fork. +3. Make your desired changes (see sections below for common cases). +4. Commit and push them on your branch. +5. Make a Pull Request to merge your changes into `dev`. +6. A code owner (probably the Scots Language Society Webmaster) will review + your Pull Request, ask for any necessary changes, and when satisfied, merge + it into `dev`. (This will update the [staging deployment](#cicd) on + [staging.scotsleidassocie.org](https://staging.scotsleidassocie.org).) +7. Code owners will merge `dev` into `main` at their discretion. (This will + update the production deployment on + [scotsleidassocie.org](https://scotsleidassocie.org).) + +### Writing a news post + +Follow this guidance alongside the [general guidance](#general-guidance). + +1. Copy and paste an existing news article in both English and Scots. You will find these in `src/content/news/en-GB` and `src/content/news/scots` respectively. -3. Rename the news article following the existing pattern, which is the date of +2. Rename the news article following the existing pattern, which is the date of publication in `YYYY-MM-DD` format followed by the title in [kebab case](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/#whatiskebabcaseanamekebabcasea) and the `.mdx` file extension. For example, `2023-12-24-eiks-an-ens-3000.mdx` would be Eiks an Ens 3000, published on the 24th of December 2023. -4. Edit the news articles to contain your desired content. -5. Check it looks OK by running the website locally with `npm install && npm start`. -6. When it looks OK, stage, commit and push your new news articles. -7. Make a pull request to merge your new news articles into the `dev` branch upstream. -8. Once a code owner approves your pull request, it'll get merged into `dev`, and +3. Edit the news articles to contain your desired content. +4. Check it looks OK by running the website locally with `npm install && npm start`. +5. When it looks OK, stage, commit and push your new news articles. +6. Make a pull request to merge your new news articles into the `dev` branch upstream. +7. Once a code owner approves your pull request, it'll get merged into `dev`, and (unless you yourself are a code owner) it is from that point no longer your problem! From that point, it'll be live on [staging.scotsleidassocie.org](https://staging.scotsleidassocie.org), and it'll go live on [scotsleidassocie.org](https://scotsleidassocie.org) once a code owner merges `dev` into `main`. -## Adding an issue of Lallans +### Adding an issue of Lallans + +Follow this guidance alongside the [general guidance](#general-guidance). 1. Add the issue number to `src/types/LallansIssueNumber.d.ts`. -2. Add the original issue cover photo as `src/images/issueXYZ.jpg`, where `XYZ` +2. Add the original issue cover photo as `src/images/lallans/issueXYZ.jpg`, where `XYZ` is the issue number. Most of the examples are `.jpg`, but the file type isn't important. 3. Make copies of the cover image that are scaled to 192 and 274 pixels wide. Name them `issueXYZ-192w.jpg` and `issueXYZ-274w.jpg` respectively. @@ -67,3 +87,78 @@ git clone https://github.com/Sycamost/lallans-wabsteid-astro.git \ Lallans page, `/furthsettins/lallans`, and the issue information should appear at `/furthsettins/lallans/XYZ`. Check both the English and Scots versions. +### Adding a Scotsoun release + +Follow this guidance alongside the [general guidance](#general-guidance). + +1. Add the release ID to `src/types/ScotsounId.d.ts`. +2. Add the original cover image as `src/images/scotsoun/scotsounXYZ.jpg`, where `XYZ` + is the release ID. Most of the examples are `.jpg`, but the file type isn't important. +3. Make a copy of the cover image which is scaled to 192 pixels wide, and name it + `scotsounXYZ-192w.jpg`. +4. Copy one of the existing Scotsoun releases in `src/data/scotsoun` and name the + copy `scotsounXYZ.ts`. +5. Edit the file you just made with the new release's information, including the + location of the correctly scaled cover image that you just made. +6. Import that data file into the Scotsoun data index file, `src/data/scotsoun/index.ts`. +7. Check that everything's working: the release should appear at the top on the + Scotsoun page, `/furthsettins/scotsoun`, and the release information should appear + at `/furthsettins/scotsoun/XYZ`. Check both the English and Scots versions. + +## Infrastructure + +The deployment infrastructure for the website is in four parts: the domains, +the SSL certificates, the hosting, and the CI/CD. + +### Domains + +The website is served on two domain names: [lallans.co.uk](https://www.lallans.co.uk) +and [scotsleidassocie.org](https://scotsleidassocie.org). The lallans.co.uk +domain is legacy, but will redirect to scotsleidassocie.org until at least +September 2024. + +Firstly, lallans.co.uk is registered with [JoomlaWired](https://www.joomlawired.com), +a hosting company specialising in hosting Joomla! and WordPress websites. We used +to host a Joomla! website with them, hence the connection. We don't host +anything with them any more, but we still rent the lallans.co.uk domain from +them. The [Scots Language Society Webmaster](mailto:lallans@hotmail.co.uk) +should have access to JoomlaWired. + +Redirecting requests to lallans.co.uk to scotsleidassocie.org is handled by +[Vercel](#hosting). + +Meanwhile, scotsleidassocie.org is rented from AWS. Again, the Webmaster should +have access to the AWS Console. + +### SSL certificates + +The SSL certificate for scotsleidassocie.org is bought from AWS Certificates +Manager. Again, the Webmaster should have access to the AWS Console. + +### Hosting + +The website is hosted on [Vercel](https://vercel.com/sycamost/lallans-wabsteid-astro). +Because we have the free plan, unfortunately only the Webmaster can access the +Vercel dashboard. + +Vercel also handles redirecting from lallans.co.uk to scotsleidassocie.org. + +### CI/CD + +Our CI/CD pipeline is, thanks to the fantastic integration between GitHub and +Vercel, no-code! We just need to make commits to the repo to see them deployed +automagically. + +Ideally, we should check everything's working on deployment before everyone on +the internet starts looking at it. For that reason, we have a staging deployment +at [staging.scotsleidassocie.org](https://staging.scotsleidassocie.org). To +update the staging deployment, simply commit to `dev` by making a Pull Request +and getting it approved by a code owner and then merged. + +To update production, you'll want to first merge your changes into `dev` by +making a Pull Request and getting it approved and merged. Once you've done that, +given it five minutes to dpeloy, and you've checked that everything looks good +on [staging.scotsleidassocie.org](https://staging.scotsleidassocie.org), +[make a Pull Request to merge dev into main](https://github.com/Sycamost/lallans-wabsteid-astro/compare/main...dev). +Once that Pull Request is approved by a code owner, merge it in and it should +update production in under five minutes. |