Update how changelog handling is done; update Spago-related things (#616

)

* Migrate changelog approach to purs-changelog

* Split CI files; add spago next/legacy sample

.procedures/redeploy-book.sh

@@ -8,7 +8,7 @@
 # - `../purescript-jordans-reference-site/src/Summary-header.md` file exists
 
 # Regenerate `mdbook`'s source content
-node .procedures/mdbook-toc.js -r "." -o "../purescript-jordans-reference-site/src" -s "Summary-header.md" -t ".ci,.git,.github,.procedures,.travis,output,book,mdbook"
+node .procedures/mdbook-toc.js -r "." -o "../purescript-jordans-reference-site/src" -s "Summary-header.md" -t ".ci,.git,.github,.procedures,.travis,output,book,mdbook,old-changelogs"
 
 cd ../purescript-jordans-reference-site
 

03-Build-Tools/04-Continuous-Integration/01-bower-based.yml

@@ -0,0 +1,61 @@
+name: CI
+
+# Run CI when a PR is opened against the branch `main`
+# and when one pushes a commit to `main`.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Run CI on all 3 latest OSes
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macOS-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Node toolchain
+        uses: actions/setup-node@v3
+        with:
+          node-version: "lts/*"
+
+      - name: Cache NPM dependencies
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+
+      - name: Setup PureScript tooling
+        run:
+          npm i -g purescript@latest purs-tidy@latest purescript-psa@latest bower
+
+      - name: Install dependencies
+        run: |
+          npm install
+          bower install --production
+
+      # Compile the library/project
+      #   censor-lib: ignore warnings emitted by dependencies
+      #   strict: convert warnings into errors
+      - name: Build source
+        run: |
+          pulp build -- --censor-lib --strict
+
+      - name: Run tests
+        run: |
+          bower install
+          pulp test
+
+      - name: Check Formatting
+        run: |
+          purs-tidy check src test

03-Build-Tools/04-Continuous-Integration.md → 03-Build-Tools/04-Continuous-Integration/02-spago-legacy-based.yml

@@ -1,64 +1,3 @@
-# Continuous Integration
-
-## GitHub Actions - `Bower`-based
-
-```yml
-name: CI
-
-# Run CI when a PR is opened against the branch `main`
-# and when one pushes a commit to `main`.
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-# Run CI on all 3 latest OSes
-jobs:
-  build:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macOS-latest, windows-latest]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v2
-
-      - uses: purescript-contrib/setup-purescript@main
-        with:
-          purescript: "0.15.7"
-          purs-tidy: "0.9.2"
-          psa: "0.8.2"
-
-      - uses: actions/setup-node@v
-        with:
-          node-version: "16"
-
-      - name: Install dependencies
-        run: |
-          npm install -g bower
-          npm install
-          bower install --production
-
-      # Compile the library/project
-      #   censor-lib: ignore warnings emitted by dependencies
-      #   strict: convert warnings into errors
-      - name: Build source
-        run: |
-          pulp build -- --censor-lib --strict
-
-      - name: Run tests
-        run: |
-          bower install
-          pulp test
-
-      - name: Check Formatting
-        run: |
-          purs-tidy check src test
-```
-
-## GitHub Actions - `Spago`-based
-
-```yml
 name: CI
 
 # Run CI when a PR is opened against the branch `main`
@@ -83,7 +22,7 @@ jobs:
       - name: Set up Node toolchain
         uses: actions/setup-node@v3
         with:
-          node-version: "16"
+          node-version: "lts/*"
 
       - name: Cache NPM dependencies
         uses: actions/cache@v3
@@ -99,7 +38,7 @@ jobs:
 
       - name: Setup PureScript tooling
         run:
-          npm i -g purescript@latest purs-tidy@latest purescript-psa@latest spago@latest
+          npm i -g purescript@latest purs-tidy@latest purescript-psa@latest spago@0.20.9
 
       - name: Install NPM dependencies
         run: npm install
@@ -128,4 +67,3 @@ jobs:
         if: runner.os == 'Linux'
         run: |
           purs-tidy check src test
-```

03-Build-Tools/04-Continuous-Integration/03-spago-next-based.yml

@@ -0,0 +1,65 @@
+name: CI
+
+# Run CI when a PR is opened against the branch `main`
+# and when one pushes a commit to `main`.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Run CI on all 3 latest OSes
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Node toolchain
+        uses: actions/setup-node@v3
+        with:
+          node-version: "lts/*"
+
+      - name: Cache NPM dependencies
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+
+      - name: Setup PureScript tooling
+        run:
+          npm i -g purescript@latest purs-tidy@latest spago@next
+
+      - name: Install NPM dependencies
+        run: npm install
+
+      - name: Cache PureScript dependencies
+        uses: actions/cache@v3
+        with:
+          key: ${{ runner.os }}-spago-${{ hashFiles('**/*.dhall') }}
+          path: |
+            .spago
+            output
+
+      - name: Build the project
+        run: |
+          npx spago build
+
+      - name: Run tests
+        run: |
+          npx spago test
+
+      - name: Check Formatting
+        if: runner.os == 'Linux'
+        run: |
+          purs-tidy check src test

03-Build-Tools/04-Continuous-Integration/Readme.md

@@ -0,0 +1,7 @@
+# Continuous Integration
+
+This folder contains copy-and-paste-able files that can be used to setup CI using GitHub Actions. Each file works for a different build tool:
+
+- Bower
+- Spago (Legacy) - the original `spago` that was written using Haskell
+- Spago (Next) - the upcoming `spago` that was written using PureScript

CHANGELOG.d/README.md

@@ -0,0 +1,77 @@
+# About
+
+This directory contains changelog entries for work that has not yet been
+released. When a release goes out, these files will be concatenated and
+prepended to `CHANGELOG.md` in a new section for that release.
+
+## For Maintainers
+
+See https://github.com/JordanMartinez/purescript-up-changelog for details of this process.
+
+## For Contributors
+
+When making a new PR, do the following steps. Each is described in the sections that follow:
+1. Add a new file to this directory where the file name follows the naming convention described below
+1. Fill that file with the proper content
+
+To ensure you're doing it correctly, see the [Checklist](#checklist)
+
+### File Naming Convention
+
+The file should be named `{PREFIX}_{SLUG}.md`.
+
+`{PREFIX}` is one of the following:
+* `breaking`: for breaking changes
+* `feature`: for new features
+* `fix`: for bug fixes
+* `internal`: for work that will not directly affect users of the project
+* `misc`: for anything else that needs to be logged
+
+`{SLUG}` should be a short description of the work you've done. The name has no
+impact on the final CHANGELOG.md.
+
+Some example names:
+* `fix_issue-9876.md`
+* `breaking_deprecate-classes.md`
+* `misc_add-forum-to-readme.md`
+
+### File Contents
+
+The contents of the file can be as brief as:
+
+```markdown
+* A short message, like the title of your commit
+```
+
+Please remember the initial `*`! These files will all be concatenated into
+lists.
+
+If you have more to say about your work, indent additional lines like so:
+
+``````markdown
+* A short message, like the title of your commit
+
+  Here is a longer explanation of what this is all about. Of course, this file
+  is Markdown, so feel free to use *formatting*
+
+  ```
+  and code blocks
+  ```
+
+  if it makes your work more understandable.
+``````
+
+You do not have to edit your changelog file to include a reference to your PR.
+The `CHANGELOG.md` updating script will do this automatically and credit you.
+
+### Checklist
+
+Use this checklist to help you remember to do everything described above.
+
+- [ ] A new file has been added to `CHANGELOG.d`
+- [ ] The file name starts with one of the `{PREFIX}` values above.
+- [ ] The file's content does not reference the PR number that introduces it
+- [ ] The file's first line (i.e. title line) starts with `* ` followed by a short description
+- If the file contains content after the first line (i.e. body part):
+    - [ ] the file has a blank line separating the title line from the body part
+    - [ ] each line in the body part is indented by at least two spaces

CHANGELOG.d/breaking_ci-file-split.md

@@ -0,0 +1,10 @@
+* Split example CI files into own files; add spago next/legacy
+
+  Previously, the `Continuous-Integration.md` file stored
+  sample CI files for GitHub Actions in a code block.
+
+  These weren't easy to copy-and-paste, so I've moved them
+  into their own files with a Readme file explaining them.
+
+  I also distinguish between Spago Legacy (Haskell-version)
+  from Spago Next (PureScript version)

CHANGELOG.d/internal_rework-changelog.md

@@ -0,0 +1,6 @@
+* Begin using [purs-changelog](https://github.com/purescript-contrib/purescript-up-changelog) to manage changelog entries.
+
+  Previous changelogs were moved into the `old-changelogs` directory.
+  The previous generated changelogs weren't as useful/readable as just
+  keeping a manual log. I also think this will be easier to track what
+  changed as I can add/edit an entry as I make the change itself.