diff --git a/.github/workflows/code-qa-js.yaml b/.github/workflows/code-qa-js.yaml index d3a4d63..58f6ad9 100644 --- a/.github/workflows/code-qa-js.yaml +++ b/.github/workflows/code-qa-js.yaml @@ -21,18 +21,18 @@ jobs: strategy: matrix: - node-version: [22.x] + node-version: [24.x] # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: - name: Checkout repository - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v6 + uses: actions/setup-node@v7 with: node-version: ${{ matrix.node-version }} - name: Cache Node.js modules - uses: actions/cache@v4 + uses: actions/cache@v6 with: path: ~/.npm key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} diff --git a/.github/workflows/code-qa-md.yaml b/.github/workflows/code-qa-md.yaml index 1cafe27..7f7ca07 100644 --- a/.github/workflows/code-qa-md.yaml +++ b/.github/workflows/code-qa-md.yaml @@ -8,14 +8,14 @@ on: paths: - "**/*.md" - ".markdownlint.json" - - ".markdownlintignore" + - ".markdownlint-cli2.jsonc" - ".github/workflows/code-qa-md.yaml" pull_request: branches: [master] paths: - "**/*.md" - ".markdownlint.json" - - ".markdownlintignore" + - ".markdownlint-cli2.jsonc" - ".github/workflows/code-qa-md.yaml" jobs: @@ -24,13 +24,13 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v6 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v6 + uses: actions/checkout@v7 + - name: Use Node.js 24.x + uses: actions/setup-node@v7 with: - node-version: ${{ matrix.node-version }} + node-version: 24.x - name: Cache Node.js modules - uses: actions/cache@v4 + uses: actions/cache@v6 with: path: ~/.npm key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} @@ -39,4 +39,4 @@ jobs: - name: Run installs run: npm ci - name: Run markdownlint on Markdown files - run: npm run lint:markdown + run: npm run lint:markdown:check diff --git a/.github/workflows/codeql-analysis.yaml b/.github/workflows/codeql-analysis.yaml index 9199647..ec76826 100644 --- a/.github/workflows/codeql-analysis.yaml +++ b/.github/workflows/codeql-analysis.yaml @@ -10,6 +10,8 @@ # supported CodeQL languages. # name: "CodeQL" +permissions: + contents: read on: push: @@ -45,7 +47,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v6 + uses: actions/checkout@v7 # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..eb627b2 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,7 @@ +{ + // Files to lint. Replaces the glob previously passed on the command line. + "globs": ["**/*.md"], + // markdownlint-cli2 does not read .markdownlintignore and does not skip + // node_modules by default, unlike markdownlint-cli. + "ignores": ["**/node_modules/**"], +} diff --git a/.markdownlintignore b/.markdownlintignore deleted file mode 100644 index 0eac630..0000000 --- a/.markdownlintignore +++ /dev/null @@ -1,32 +0,0 @@ -# dependencies -**/node_modules -/.pnp -.pnp.js - -# Build files -*.min.js -*.min.css -sw.js -*.js.map - -# Packages -src/scripts/libraries - -# misc -.DS_Store -.env.local -.env.development.local -.env.test.local -.env.production.local -.vscode - -# workbox -workbox-config.js -src/serviceWorker - -# Visual Studio Code -.vscode/settings.json -.vscode/launch.json - -# Ignore minified files -*.min.* \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3c0129..bf32600 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,55 +2,19 @@ We are open to any contributions at any time. When contributing, we ask you to please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. -Please note we have a code of conduct, please follow it in all your interactions with the project. +Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project. ## Pull Request Process -1. Ensure any install or build dependencies are removed before the end of the layer when doing a build. -2. Update the [README.md](README.md) with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters. -3. Increase the version numbers in any examples files and the [README.md](README.md) to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). -4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you. +1. Run `npm run validate` before opening the pull request. It runs Prettier, ESLint, the Jest unit tests, the Cypress end-to-end tests, and markdownlint in sequence, which is the same ground the pipeline covers. See [Testing & Validation](docs/guide/testing.md). +2. Update the documentation that your change affects, which means [README.md](README.md) for anything a visitor or operator would notice and the relevant guide under [docs/](docs/index.md) for anything a contributor would. +3. Record the change in [CHANGELOG.md](CHANGELOG.md) under the version the pull request would release. The format is [Keep a Changelog](http://keepachangelog.com/) and the versioning scheme is [SemVer](http://semver.org/). +4. When raising the version, update it in [package.json](package.json) and in the Sentry `release` value in [index.html](index.html), which the inline comment beside it also asks for. The same file sets an `app-version` tag through `Sentry.configureScope`, a function the Sentry JavaScript SDK removed in version 8 while the page loads version 10, so that tag needs the call migrated to `Sentry.getCurrentScope()` before it is worth maintaining. +5. Wait for the pull request checks to pass. [code-qa-js.yaml](.github/workflows/code-qa-js.yaml) covers the JavaScript quality gates, [code-qa-md.yaml](.github/workflows/code-qa-md.yaml) covers markdown, and [codeql-analysis.yaml](.github/workflows/codeql-analysis.yaml) runs CodeQL analysis. +6. You may merge the pull request once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you. -## Code of Conduct - -### Our Pledge - -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience nationality, personal appearance, race, religion, or sexual identity and orientation. - -### Our Standards - -Examples of behavior that contributes to creating a positive environment include: - -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -- The use of sexualized language or imagery and unwelcome sexual attention or advances -- Trolling, insulting/derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or electronic address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Our Responsibilities +There is no build step in this repository. The one generated artifact is the service worker, regenerated with `npm run workbox` after adding or renaming assets that need precaching. -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. - -### Scope - -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. - -### Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. - -### Attribution +## Code of Conduct -This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/) +This project follows the Contributor Covenant. The full text, including the reporting process and the enforcement guidelines, is in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). diff --git a/SECURITY.MD b/SECURITY.md similarity index 100% rename from SECURITY.MD rename to SECURITY.md diff --git a/cypress/support/commands.js b/cypress/support/commands.js index fe5420f..04b66f4 100644 --- a/cypress/support/commands.js +++ b/cypress/support/commands.js @@ -1,27 +1,5 @@ /// -// *********************************************** -// This example commands.js shows you how to -// create various custom commands and overwrite -// existing commands. -// -// For more comprehensive examples of custom -// commands please read more here: -// https://on.cypress.io/custom-commands -// *********************************************** -// -// -// -- This is a parent command -- -// Cypress.Commands.add('login', (email, password) => { ... }) -// -// -// -- This is a child command -- -// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... }) -// -// -// -- This is a dual command -- -// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... }) -// -// -// -- This will overwrite an existing command -- -// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... }) -// + +// Custom Cypress commands and command overwrites for the end-to-end suite. +// Loaded by cypress/support/e2e.js before every spec file. +// See https://on.cypress.io/custom-commands for the command API. diff --git a/cypress/support/e2e.js b/cypress/support/e2e.js index f4a4dab..ef913e5 100644 --- a/cypress/support/e2e.js +++ b/cypress/support/e2e.js @@ -1,19 +1,5 @@ -// *********************************************************** -// This example support/e2e.js is processed and -// loaded automatically before your test files. -// -// This is a great place to put global configuration and -// behavior that modifies Cypress. -// -// You can change the location of this file or turn off -// automatically serving support files with the -// 'supportFile' configuration option. -// -// You can read more here: -// https://on.cypress.io/configuration -// *********************************************************** -// Import commands.js using ES2015 syntax: -import "./commands"; +// Support file loaded automatically before every end-to-end spec. +// Global configuration and any behaviour that modifies Cypress belongs here. +// The supportFile configuration option controls whether this file is loaded. -// Alternatively you can use CommonJS syntax: -// require('./commands') +import "./commands"; diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md index 03cf831..71ef598 100644 --- a/docs/architecture/data-flow.md +++ b/docs/architecture/data-flow.md @@ -16,7 +16,7 @@ flowchart TD subgraph Init["Initialization"] B1["Scripts load:
jQuery, Showdown,
Bootstrap, Sentry"] B2["Sentry error tracking
is configured"] - B3["Service worker
registers if offline
caching enabled"] + B3["Service worker registers
if the browser
supports it"] end subgraph Metadata["Load Metadata"] @@ -34,7 +34,7 @@ flowchart TD subgraph Fetch["Fetch Article Content"] E1["Construct article path:
authorAuthorName/
YYYY-MM-DD_Title/
Title.md"] - E2["Fetch markdown file
from CDN or cache"] + E2["Fetch markdown file
from site origin
or service worker cache"] E3["Store raw markdown
ArticleFiller.articleMd"] end @@ -107,17 +107,18 @@ flowchart TD When [index.html](../../index.html) loads: 1. HTML is parsed -2. External scripts and stylesheets are downloaded: - - Bootstrap CSS (from CDN) - - jQuery (from CDN) - - Showdown.js (from CDN) - - Sentry SDK (from sentry-cdn.com) - - Custom [index.js](../../src/scripts/index.js) (local) - -3. Inline `