Skip to content

Latest commit

 

History

History
239 lines (170 loc) · 11.2 KB

README.dev.md

File metadata and controls

239 lines (170 loc) · 11.2 KB
Raw

Developer documentation

If you are looking for user documentation, go here.

Prerequisites

  • npm CLI: Package manager command line interface shipped with NodeJS.

Code editor

Virtual environments

nvm or nvs can be used to manage node versions.

Installing the dependencies

The command below will install npm dependencies

npm clean-install

Starting the development server

You can start the development server by running

npm run dev

Use a browser to navigate to localhost:8080/cff-initializer-javascript/ to see the website.

Building the application

The command below will build the application and save the output in docs/ folder. This is what we serve in the demo page.

npm run build

Debugging

Tests

Unit tests

We use Jest for unit tests. The unit tests can be found under test/jest/__tests__/ folder.

You can run the test with

npm run test:unit:ci

You can also use the Majestic web interface to run the unit tests in your browser.

npm run test:unit:ui

End-to-end tests

We use Cypress for end-to-end tests. These tests can be found under the cypress/e2e folder.

You can start Cypress with

npm run cypress:open

Select "E2E Testing", which should be configured already and select the desired browser and click the start button.

A browser will open with the list of tests, which can be explored. It should look like this:

Cypress E2E specs list

Cypress E2E specs list. Image is from https://docs.cypress.io/guides/end-to-end-testing/writing-your-first-end-to-end-test

Click on the spec file. The next screen will show the tests being executed. If anything goes wrong, you will see it in red. For more information, check https://docs.cypress.io/guides/end-to-end-testing/testing-your-app#What-you-ll-learn.

Linting and formatting

npm run lint

try to automatically fix linting issues with

npm run lint -- --fix

To run linting on commit, you can install a git commit hook with

npx husky install

Publishing

This app is published using GitHub pages automatically by the Publish workflow. The way this works is:

For this to work, a few things have to be set up for first time use:

  • A gh-pages has to exist before the action is run. You can create an orphan branch to have a clean history with the following commands:
git checkout --orphan gh-pages
git rm -rf .
# git rm other files and folders if necessary
touch index.html
git add index.html
git commit -m "gh-pages created"
git push origin gh-pages

Previewing

This is app is previewed using Netlify automatically by the Preview workflow. The main branch is previewed into https://cffinit.netlify.app/main and each Pull Request is previewing into a https://cffinit.netlify.app/PRXXX page. The way this works is:

  • The branch gh-preview is served by Netlify. There is a folder main and several folders PRXXX in that branch.
  • After a Pull Request or a push to main is created, the workflow runs.
  • The workflow changes the publicPath configuration in quasar.conf.js to reflect the folder main or PRXXX.
    • This is stored in a environment variable PUBLICPATH to be used later.
    • We use sed with a -i to replace the value in-place.
  • The workflow builds the app (using the npm run build command) into a folder ./dist.
  • The GitHub action peaceiris/actions-gh-pages@v3 pushes the contents of ./dist to the branch gh-preview in the indicated path.
  • After the push is complete, we create a comment on the pull request (if applicable) with the link to the preview page.

For this to work, you need a gh-preview branch to exist and to enable write permissions for secrets.GITHUB_TOKEN. See the section on Publishing for details on how to do this.

Making a release

This section describes how to make a release in 2 parts:

  1. preparation
  2. making a release on GitHub

(1/2) Preparation

  1. Create a new branch release-x.y.z.
  2. Run the update-version script running bash .github/update-version.sh x.y.z and check the result. It should
    1. Update the version, the date-released, and possibly other information in CITATION.cff;
    2. Generate an updated version of .zenodo.json if needed using cffconvert;
    3. Update the version field in package.json and package-lock.json;
    4. Update the version in the landing page footer; and
    5. Update the version in the app footer.
  3. Run npm run lint and make sure the linter does not complain.
  4. Run the unit tests with npm run test:unit:ci.
  5. Run the end-to-end tests with npm run cypress:run.
  6. Commit and push all changes to GitHub, make a PR.
  7. Inspect the Netlify preview website.
  8. Review the PR and merge to the default branch main.

(2/2) Making a release on GitHub

  1. Make a release on GitHub.
  2. Check that the Publish workflow was triggered by making the release, and that it was successful.
  3. Inspect the deployed github.io website https://citation-file-format.github.io/cff-initializer-javascript/.
  4. Verify that the Preview workflow was triggered on release deploying a preview of the tag to https://cffinit.netlify.com/TAG.
  5. Check whether the zenodraft workflow was triggered correctly when the GitHub release was created. If it was not, then trigger it manually.
  6. Go to Zenodo and verify that the new DOI was created by zenodraft.

References

Links to documentation or tutorials related to technologies/tools we use in the project are shown below. The notes about how we came to this technology stack, design and personas can be found in project-docs/ folder.

  • Single Page App: The cffinit app will be a SPA. So app feels like a native app and no server-side code needs to run.
  • Figma: A vector graphics and prototyping editor used to developed the wireframes and interaction designs.
  • TypeScript: Typed JavaScript language used for lowering maintenance cost.
  • Vue.js v3: A frontend JS framework for building user interfaces.
  • Vue.js Composition API: Is style of writing UI components to group logical concerns like state management.
  • Quasar: A UI framework, a group of UI components, that follow Material design guidelines to make a coherent/pleasing user interface.
  • GitHub pages: Hosting of static HTML files. The build app (in docs folder) is deployed on it.
  • Husky: Automaticly runs checks before pushing changes to GitHub.
  • Jest: Testing framework to run unit tests and perform test assertions.
  • ESLint: To get constistent code style and prevent errors the industry standard linter ESLint is used.
  • Majestic Web UI: Web UI for unit tests using Jest

User stories/Requirements

Update existing CFF

Constraints:

  • Files that were not created by cffinit should still be accepted. This implies that
    • Fields like preferred-citation should be handled.
    • Old valid files should be handled.
  • Ignore or fix small mistakes, to make the experience smoother.
  • Updating is like continuing from a finished state, so all screen should be marked as visited.

Here is the list of situations that can happen:

  • If the input is not valid YAML, raise an error and don't proceed.
  • If the input is not an object, raise an error and don't proceed. This includes vectors and strings.
  • Keys at root level that are not part of the cff object are passed to extraCffFields. A warning is printed, but proceed.
  • If an author is not a Person nor Entity, print the infringing fields and drop the author.
  • If an author does not have enough fields to check whether it is a Person or Entity (e.g., only orcid), then use Person.
  • Keys at nested identifiers levels are ignored. A warning is printed but proceed.
  • Radio values ('type' and 'identifiers/type') should be sanitized.
  • If an old cff-version was present, warn that a newer version will be used.
  • If no cff-version was found, no need to warn.
  • 'date-released' should be sanitized so it is a 'yyyy-mm-dd' string, and not a Javascript date.
  • Input validation is only done a posteriori, so don't check it during update.
  • Special situations (such as cff-version and type above) should be handled explicitly and documented.
  • If parsing is successful, give positive feedback.

Deprecated:

  • Keys at nested levels (e.g., authors) are ignored. A warning is printed, but proceed.
    • Deprecated because the author can be a Person or Entity. So to check that, we have to decide based on the fields what to check.