Skip to content

Latest commit

 

History

History
140 lines (101 loc) · 5.27 KB

README.dev.md

File metadata and controls

140 lines (101 loc) · 5.27 KB
Raw

Developer documentation

Tech stack

  1. Vue 3
  2. Vite
  3. Vitest
  4. TypeScript
  5. vite-ssr-plugin

IDE / dev setup

We recommend using Volar VSCode extension for improved development experience. The project uses Vue 3 <script setup> SFCs, check out the script setup docs to learn more.

  1. VS Code
  2. Volar

Development installation

cd <some dir>
git clone https://github.com/ardc-fair-checklist/ardc-fair-checklist.github.io .
npm install

npm scripts

  • npm run build: build the project for production, output files in ./dist
  • npm run coverage: run the tests once and calculate coverage using @vitest/coverage-c8
  • npm run dev: build the project for development, watch files for changes, serve output files on localhost.
  • npm run lint: run eslint with configuration from .eslintrc
  • npm run prod: shorthand for npm run build && npm run server:prod
  • npm run server: serve the development build
  • npm run server:prod: serve the production build
  • npm run test: run the unit tests in watch mode using vitest

relevant version info from npm list:

├── @types/[email protected]
├── @types/[email protected]
├── @types/[email protected]
├── @vitejs/[email protected]
├── @vue/[email protected]
├── @vue/[email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
└── [email protected]

Versioning strategy

In the current app, there are multiple entities that could be versioned, namely the software questions JSON and the software questions app. The DRY (Don't Repeat Yourself) principle would suggest to make one app that can be used to render any version of the questions. However, this becomes more difficult to maintain as more versions of the questions are introduced. We therefore chose to have one directory for each version. That one directory contains all the components, along with all the data needed to render the app for that particular version of the questions. Naturally, this comes at the cost of having duplicate code between versions. Each version is assigned its own route, and can choose to do its own processing on supplied query parameters. Only the contents of public/, renderer/, and server/ are shared across versions.

Publishing

GitHub Pages

There is a GitHub action /.github/workflows/publishing.yml that builds the project for production and hosts it at https://fairsoftwarechecklist.net/, which is owned by Netherlands eScience Center. The GitHub action can be triggered manually via the GitHub user interface.

GitHub

Don't make GitHub releases manually, instead let the zenodraft workflow do it. See #92.

Zenodo

See #92 for avoiding a problem when publishing.

There is a GitHub action /.github/workflows/zenodraft.yml that publishes a snapshot of main to Zenodo, makes a release on GitHub, and tags the corresponding SHA. The workflow purposely does not finalize the depostion on Zenodo. It must be published manually by clicking the "Publish" button on Zenodo after inspection of the draft's metadata. The GitHub action can be triggered manually via the GitHub user interface.

Adding a new version

Let's say the current latest version is v0.2, and the version you want to make is v1. You would do the following:

cd <project root>
cp -r pages/v0.2 pages/v1

Then, add the new version string to the relevant part of the state in versions.ts:

nano renderer/versions.ts

where it says

['v0.1', 'v0.2']

add the next version identifier:

['v0.1', 'v0.2', 'v1']

Start the development server:

npm run dev

Check browser:

# add BASE_URL if you have it enabled, see vite.config.js
open http://localhost:3000

Now make whatever changes you want under pages/v1. The page should update through hot module reloading. Existing badges that point to any version that isn't the latest should still resolve to the correct (older) version page, but will now display a message prompting users to update.