From 851c66945c24d5f232947ac607b688b66303f161 Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Wed, 28 Feb 2024 15:52:35 -0500 Subject: [PATCH 01/26] first commit, adding temp files, placeholder content, and getting an idea of information needed readme badge updates readme updating misc Readme updates --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/SUPPORT.md | 10 + .gitignore | 79 ++++ AUTHORS.md | 22 + CHANGELOG.md | 33 ++ CODE_OF_CONDUCT.md | 142 +++++++ CONTRIBUTING.md | 139 ++++++ README.md | 703 ++++++++++++++++++++++++++----- 8 files changed, 1012 insertions(+), 118 deletions(-) create mode 100644 .github/SUPPORT.md create mode 100644 AUTHORS.md create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f28b0de8c..fbfad5f96 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,4 +12,4 @@ ## Is there a release notes update needed for this change?: -## Additional documentation: +## Additional documentation: \ No newline at end of file diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 000000000..8d74d941f --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,10 @@ + +# Looking for support? We want to help + +Please post your question to X (#) using the Timber tag. + +## Other places + +You can use [GitHub Discussions](#) to open up questions and engage in discussions with the contributors and other users. + +Please don't post to the [EXAMPLE forum](#). You might see a response, but it will just redirect you to either GitHub (for bugs/issues) or StackOverflow (for usage/support questions). diff --git a/.gitignore b/.gitignore index a9076c592..a53c72760 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,82 @@ yarn-error.log* /dev-env/dataverse /dev-env/dataverse-sample-data /packages/design-system/.nyc_output + + +# Compiled source # +################### +*.com +*.class +*.dll +*.exe +*.o +*.so +_site/ + +# Packages # +############ +# it's better to unpack these files and commit the raw source +# git has its own built in compression methods +*.7z +*.dmg +*.gz +*.iso +*.jar +*.rar +*.tar +*.zip + +# Logs and databases # +###################### +*.log +*.sql +*.sqlite + +# OS generated files # +###################### +.DS_Store +.DS_Store? +.Spotlight-V100 +.Trashes +Icon? +ehthumbs.db +Thumbs.db + +# Vim swap files # +################## +*.swp + +# Python # +################# +*.pyc +*.egg-info/ +__pycache__/ +*.py[cod] +.env +.python-version + +# pyenv # +######### +.python-version + +# Django # +################# +*.egg-info +.installed.cfg + +# Unit test / coverage reports +################# +htmlcov/ +.tox/ +.coverage +.cache +nosetests.xml +coverage.xml + +# Front-End # +############# +node_modules/ +bower_components/ +.grunt/ +src/vendor/ +dist/ \ No newline at end of file diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 000000000..9708d6a30 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,22 @@ +# Below is a list of people and organizations that have contributed + +# to the Dataverse Frontend project. Names should be added to the list like so: + +# + +# Name/Organization + +# + +# Anyone who has contributed to the Dataverse Frontend project in any way (not + +# limited to submitting PRs) is welcome to submit a PR to add their + +# name to this file. + +# + +# Thanks to everyone for your contributions! + +Harvard University IQSS Team +FirstName LastName diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..99d2ef963 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Change Log + +Resources for generating a changelog: + +[skywinder/Github-Changelog-Generator](https://github.com/skywinder/Github-Changelog-Generator) - generates a full changelog that overwrites the existing CHANGELOG.md. + +[hzalaz/wt-oss-milestone-changelog](https://github.com/hzalaz/wt-oss-milestone-changelog) - generates a snippet of Markdown that can be added to a CHANGELOG.md. + +[conventional-changelog/conventional-changelog](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli) - generates a full changelog based on commit history with the option to append to an existing changelog. + + + +All notable changes to this project will be documented in this file. +We follow the [Semantic Versioning 2.0.0](http://semver.org/) format. + +## x.y.z - YYYY-MM-DD + +### Added + +- Lorem ipsum dolor sit amet + +### Deprecated + +- Nothing. + +### Removed + +- Nothing. + +### Fixed + +- Nothing. +- diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..b4434fdfe --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,142 @@ +# Dataverse® Code of Conduct + +## Our Pledge + +[Institute for Quantitative Social Science](http://www.iq.harvard.edu/) (IQSS) + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or + advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Scope + +We expect everyone on the IQSS Dataverse team, and those contributing to our open source community, to exhibit +these behaviors and abide by applicable federal laws and Harvard University policies. + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## What We Strive For + +At IQSS, we strive to create a welcoming and inclusive culture that empowers people to share, preserve, cite, explore, and analyze research data. That kind of atmosphere requires an open exchange of ideas balanced by thoughtful guidelines. Examples of behavior that contributes to a positive environment for our open source community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community and public + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders 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, and will communicate reasons for moderation +decisions when appropriate. + +## Enforcement Guidelines + + + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at IQSS (EMAIL). +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..43f6b1790 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,139 @@ +# Guidance on how to contribute + +> All contributions to this project will be released under the Apache License, Version 2.0. +> By submitting a pull request or filing a bug, issue, or +> feature request, you are agreeing to comply with this waiver of copyright interest. +> Details can be found in our [LICENSE](LICENSE). + +Hey there! We’re really happy you’ve found your way here. Dataverse® is a community project that is developed by people from all over the world. We appreciate any help. + +Before you start working on something we would suggest talking to us in the [TODO: discussion forum](#) or asking a question on [TODO: GoogleGroups/Zulip](#). You can also contact us via the chat widget on the [TODO: main Dataverse website](#). + +Here are ways to get involved: + +1. [Star](https://github.com/iqss/dataverse-frontend/stargazers) the project! +2. Answer questions that come in through [GitHub issues](https://github.com/iqss/dataverse-frontend/issues?state=open). +3. [Report a bug](https://github.com/iqss/dataverse-frontend/issues/new?assignees=&labels=&projects=&title=%5BBUG%5D+Your+title) that you find. +4. Share a project you’ve built with Dataverse. This helps transfer knowledge about best practices, etc. _Add it to the [TODO: Showcase list](https://github.com/iqss/dataverse-frontend/foo/wiki/Showcase)_. +5. Browse ["help wanted"](https://github.com/iqss/dataverse-frontend/labels/help%20wanted) and ["good first issue"](https://github.com/iqss/dataverse-frontend/labels/good%20first%20issue) labels for areas of Dataverse/JavaScript/code you know well to consider, build or document. +6. Answer questions on [Google Groups | posted under the «Dataverse» tag](#). You can also [TODO: subscribe to a tag](#) via email to get notified when someone needs help. +7. Answer questions and join in on [Google Groups/Zulip Discussions](#). + +## Using the issue tracker + +Use the issue tracker to suggest feature requests, report bugs, and ask questions. +This is also a great way to connect with the developers of the project as well +as others who are interested in this solution. + +Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in +the issue that you will take on that effort, then follow the _Changing the code-base_ +guidance below. + +## Documenting + +This is probably one of the most important things you can do as a contributor and probably one of the easiest things you can do. There are two big pieces of documentation you can edit right here on github! + +The first is the [TODO: Readme?](https://www.codenameone.com/javadoc/) which you can edit directly in the source code, if there is an ommission or a mistake you can just press the edit button on the file and make the change directly even without an IDE. These pull requests are highly appreciated and will help future generations of developers! + +The [Dataverse developer guide](https://guides.dataverse.org/en/latest/developers/index.html) is generated from [TODO: the wiki pages of this project](https://github.com/iqss/dataverse-frontend/foo/wiki/). You can just [TODO: edit the wiki directly](#), and your changes will reflect in the developers guide. Don't forget to edit the authors section and add some credit! + +Please try to maintain the convention for the guide as we automate many pieces in the guide generation and conversion. + +## Changing the code-base + +Generally speaking, you should fork this repository, make changes in your +own fork, and then submit a pull request. All new code should have associated +unit tests that validate implemented features and the presence or lack of defects. +Additionally, the code should follow any stylistic and architectural guidelines +prescribed by the project. In the absence of such guidelines, mimic the styles +and patterns in the existing code-base. + +Pull requests are highly appreciated. More than [X people](https://github.com/iqss/dataverse/graphs/contributors) have written parts of Dataverse (so far). Here are some guidelines to help: + +1. **Solve a problem** – Features are great, but even better is cleaning-up and fixing issues in the code that you discover. +2. **Write tests** – This helps preserve functionality as the codebase grows and demonstrates how your change affects the code. +3. **Write documentation** – Timber is only useful if its features are documented. This covers inline documentation of the code as well as documenting functionality and use cases in the Guides section of the documentation. +4. **Small > big** – Better to have a few small pull requests that address specific parts of the code, than one big pull request that jumps all over. +5. **Comply with Coding Standards** – See next section. + +## Preparations + +After you’ve forked the Dataverse Frontend repository, you should install all npm dependencies. + +```bash +npm install +``` + +## Coding Standards + +We use [TODO: EasyCodingStandard](https://github.com/symplify/easy-coding-standard) for Dataverse’s code and code examples in the documentation, which follows the [TODO: X: Extended Coding Styles](#). + +We use ESLint to automatically check and apply the coding standards to our codebase, reducing the manual work to a minimum. + +### Check and apply coding standards + +To run all checks, you can run the `lint` script. + +```bash +npm run lint +``` + +You can also apply coding style fixes automatically. + +```bash +npm run lint:fix +``` + +### Check and apply formatting standards + +Launches the prettier formatter. We recommend you to configure your IDE to run prettier on save. + +```bash +npm run format +``` + +### Enforcing coding standards using pre-commit hooks + +We use [TODO: XX](#) to add pre-commit hooks which automatically check the committed code changes for any coding standard violations. + +### Tests + +`npm run test:unit` Launches the test runner for the unit tests in the interactive watch mode. +If you prefer to see the tests executing in cypress you can run `npm run cy:open-unit` +You can check the coverage with `npm run test:coverage` + +`npm run test:e2e` Launches the Cypress test runner for the end-to-end tests. +If you prefer to see the tests executing in cypress you can run `npm run cy:open-e2e` + +### Other commands + +There are more commands that we use to ensure code quality. Usually, you won’t need them. + + + +## Process + +All PRs receive a review from at least one maintainer. We’ll do our best to do that review as soon as possible, but we’d rather go slow and get it right than merge in code with issues that just lead to trouble. + +### GitHub reviews & assignments + +You might see us assign multiple reviewers, in this case these are OR checks (i.e. either Person1 or Person2) unless we explicitly say it’s an AND type thing (i.e. can both Person3 and Person4 check this out?). + +We use the assignee to show who’s responsible at that moment. We’ll assign back to the submitter if we need additional info/code/response, or it might be assigned to a branch maintainer if it needs more thought/revision (perhaps it’s directly related to an issue that's actively being worked on). + +Once approved, the lead maintainer for the branch should merge the PR into the `develop` branch. + +### Codeowners + +We use a [CODEOWNERS](https://github.com/iqss/dataverse-frontend/blob/master/.github/CODEOWNERS) file to define who gets automatic review invitations. + +## Ownership + +By contributing code you are granting _(`Dataverse`)_ shared ownership of your work. You still own it but _(`Dataverse`)_ will have the right to relicense your work based on our needs & treat this work as if it was developed by a _(`Dataverse`)_ engineer. + +## Browser support + + diff --git a/README.md b/README.md index a91b5db61..c2cf9fc2d 100644 --- a/README.md +++ b/README.md @@ -1,121 +1,348 @@ -# Dataverse Frontend - -[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) -[![Tests](https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml/badge.svg)](https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml) -[![Unit Tests Coverage](https://coveralls.io/repos/github/IQSS/dataverse-frontend/badge.svg?branch=develop)](https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop) - -## Demo videos + + + + + + + + + + + +
+
+ + Logo + +

Dataverse Frontend

+

+ _Tagline_ +
+ Explore the docs » +
+
+ View Demo· + Report Bug· + Request Feature. +

+
+ + +
+ Table of Contents +
    +
  1. + About The Project + +
    2. +
  2. + Getting Started + +
    3. +
  3. Additional Configurations + +
    4. +
  4. Development
    5. +
  5. Components
    6. +
  6. Code
    7. +
  7. Usage
    8. +
  8. Roadmap
    9. +
  9. Contributing
    10. +
  10. License
    11. +
  11. Contact
    12. +
  12. Acknowledgments
    13. +
+
+ + + +## About The Project + +[![Product Name Screen Shot][product-screenshot]](https://example.com) + + + +--- + +### Demo videos - 2023-08-01: [View mode of the dataset page](https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ) - 2023-12-13: [Files table on the dataset page](https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ) -## Getting Started +### What is Dataverse? + +The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [![Dataverse Website][dataverse-web-link]](https://dataverse.org/about) + +### What is Dataverse Frontend & How do they differ? + +The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations and utilize the JavaScript framework of their choice. + +**The goals of Dataverse Frontend:** + +- Modernize the application +- Separate the frontend and backend logic, transition away from Monolithic Architecture +- Reimagine the current Dataverse backend as a headess API-first instance. +- The Dataverse Frontend becomes a stand-alone SPA (Single Page Application) +- Modularize the UI to allow third-party extension of the base project +- Increase cadence of development, decrease time between release cycles to implement new features +- Introduce testing automation +- Give priority and transparency to coding and design to support Harvard University's commitment to ensuring the highest standards for Accessibility Compliance +- Empower the community to create, contribute, and improve. + +**New Features:** + +- Node Application using ReactJS for the project baseline +- Native localization support through the i18n library +- Accessibility compliant code built from the ground-up +- Improved modularity via Web Components +- Cypress testing automation +- Storybook for UI Component Library + +### How existing Dataverse installations may be affected + +- The existing Dataverse API will be added to and extended from the present backend architecture while the existing UI and current Dataverse functionalities are preserved. +- The SPA will continue its life as a separate application, supported on its own maintenance schedule. +- When the SPA has matured enough for an official release, we will switch to the new version and the old backend (Link to repository) will be moved into maintenance mode with no new features being introduced and focusing only on critical bugfixes. -First install node >=16 and npm >=8. Recommended versions `node v19` and `npm v9`. + -### Create a `.npmrc` file and add a token +#### Changes from the original JSF application -To install the [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) -from the GitHub registry, necessary for connecting with the Dataverse API, follow these steps to create an `.npmrc` file in -the root of your project using your GitHub token. +
+Expand -1. **Copy `.npmrc.example`** +##### Changes from the Style Guide - Duplicate the `.npmrc.example` file in your project and save it as `.npmrc`. +The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. + +###### Links + +We added an underline to links to make them accessible. + +###### File label + +Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies +the secondary color to the labels automatically, the color of the file label is now the global secondary color which is +a lighter shade of grey than what it used to be. -2. **Replace the Token** +We changed the citation block to be white with a colored border, to make the text in the box more accessible. + +##### Changes in functionality behavior - Open the newly created `.npmrc` file and replace `YOUR_GITHUB_TOKEN` with your actual GitHub token. +Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. - ```plaintext - legacy-peer-deps=true +###### Dataset files tab search - //npm.pkg.github.com/:_authToken= - @iqss:registry=https://npm.pkg.github.com/ - ``` +The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. -#### How to Get a GitHub Token +The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search options are available for all versions in the same way, homogenizing behavior, although losing the possibility of using the Solr grammar. -If you don't have a GitHub token yet, follow these steps: +The decision of this change is made on the assumption that Solr may not be required in the context of files tab search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that the assumption is incorrect, we will work on extending the search capabilities to support Solr. -1. Go to your GitHub account settings. +
-2. Navigate to "Developer settings" -> "Personal access tokens." +

(back to top)

-3. Click "Personal access tokens" -> "Tokens (classic)" -> "Generate new token (classic)". + -4. Give the token a name and select the "read:packages" scope. +## Getting Started -5. Copy the generated token. + -6. Replace `YOUR_GITHUB_AUTH_TOKEN` in the `.npmrc` file with the copied token. +To get a local copy up and running follow these simple example steps. -Now, you should be able to install the Dataverse JavaScript client using npm. +### Prerequisites -### `npm install` +1. Node **node >=16** and NPM **npm >=8**. Recommended versions for this project are `node v19` and `npm v9`. +1. Docker. We use [![DockerDesktop][DockerBadge]][Docker-url]. -Run this command to install the dependencies. You may see a message about vulnerabilities after running this command. \ -Please check this announcement from Create React App repository https://github.com/facebook/create-react-app/issues/11174 . -These vulnerabilities won't be in the production build since they come from libraries only used during the development. +1. Add your NPM and GitHub Tokens. In order to connect with the Dataverse API, develoeprs will need to install [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) from the GitHub registry by following the steps outlined below: +1. Navigate to the project directory root and duplicate the `.npmrc.example` file, saving the copy as `.npmrc`. + > ```sh + > # root project directory + > cp .npmrc.example .npmrc + > ``` +1. Follow the steps outlined below to generate a [personal access token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) used to interface with the GitHub API. -### `cd packages/design-system && npm run build` +> 1. Getting a GitHub token +> 1. Go to your GitHub **[Personal Access Tokens](https://github.com/settings/tokens)** settings +> 2. Select **_Generate new token (classic)_** +> 3. Give the token a name and select scope **_`read:packages`_** +> 4. Copy the generated token and replace the string _**`YOUR_GITHUB_AUTH_TOKEN`**_ in the **_`.npmrc`_** file in the project base. +> Now, you should be able to install the [Dataverse JavaScript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) client using npm. -Run this command to build the UI library. This is needed to be able to run the app. +```plaintext +legacy-peer-deps=true -## Available Scripts + //npm.pkg.github.com/:_authToken= + @iqss:registry=https://npm.pkg.github.com/ +``` -In the project directory, you can run at any time: +### Installation & Setup -### `npm start` +_Below is an example of how you can instruct your audience on installing and setting up your app. This template doesn't rely on any external dependencies or services._ -Runs the app in the development mode. -Open [http://localhost:5173](http://localhost:5173) to view it in your browser. +1. Install the project & its dependencies -The page will reload when you make changes. -You may also see any lint errors in the console. +```sh +# root project directory +npm install +``` -### `npm run test:unit` +You may see a message about vulnerabilities after running this command. -Launches the test runner for the unit tests in the interactive watch mode. -If you prefer to see the tests executing in cypress you can run `npm run cy:open-unit` -You can check the coverage with `npm run test:coverage` +Please check this announcement from Create React App repository [facebook/create-react-app#11174](https://github.com/facebook/create-react-app/issues/11174). These vulnerabilities will not be included in the production build since they come from libraries only used during development. -### `npm run build` +2. Build the UI Library, needed for running the application. -Builds the app for production to the `dist` folder. +```sh + cd packages/design-system && npm run build +``` -### `npm run preview` +#### Additional scrips available -Locally preview the production build. +**Running & building the app:** -### `npm run test:e2e` +Run the app in the development mode. Open [http://localhost:5173](http://localhost:5173) to view it in your browser. -Launches the Cypress test runner for the end-to-end tests. -If you prefer to see the tests executing in cypress you can run `npm run cy:open-e2e` +```sh +# root project directory +npm start +``` -### `npm run lint` +The application will actively watch the directory for changes and reload when changes are saved. You may also see any existing linting errors in the console. -Launches the linter. To automatically fix the errors run `npm run lint:fix` -### `npm run format` +```sh +# Build the app for production to the `/dist/` directory: +npm run build +# Locally preview the production build: +npm run preview -Launches the prettier formatter. We recommend you to configure your IDE to run prettier on save. +``` -### `npm run storybook` +**Storybook:** Runs the Storybook in the development mode. -There are 2 Storybook instances, one for the Design System and one for the Dataverse Frontend. +There are 2 Storybook instances, one for the general Design System and one for the Dataverse Frontend component specifications. + +```sh +# $ cd packages/design-system +npm run [build-]storybook + +# 'npm run storybook` should automatically open the following urls in your default browser +# Dataverse Frontend Storybook at: http://localhost:6006/ +# Dataverse Design System Storybook at: http://localhost:6007/ +``` + +Note that both Storybook instances are also published to Chromatic as part of the build and merge processes, located at: + +[![DataverseFrontend][DataverseFrontend-Chromatic]][DataverseFrontend-Chromatic-url] + + +[![DataverseDesignSystem][DataverseDesignSystem-Chromatic]][DataverseDesignSystem-Chromatic-url] + + + + +**Testing with Cypress:** + +Use the following commands to ensure your build passes checks for coding standards and coverage: + +```sh +# root project directory +# Launches the Cypress test runner for the end-to-end [or unit] tests: +npm run test:e2e [test:unit] +# If you prefer to see the tests executing in Cypress you can run: +npm run cy:open-e2e [cy:open-unit] +# See current code coverage +npm run test:coverage + +``` + + +**Using `grep` with Cypress** + +The project includes [@cypress/grep](https://www.npmjs.com/package/@cypress/grep) for running specific tests. -Open [http://localhost:6006](http://localhost:6006) to view the Dataverse Frontend Storybook in your browser. -Open [http://localhost:6007](http://localhost:6007) to view the Design System Storybook in your browser. -Note that both Storybook instances are also published to Chromatic: +Some examples used by the grep library are below for reference: -- [Dataverse Frontend](https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd) -- [Dataverse Design System](https://www.chromatic.com/builds?appId=646fbe232a8d3b501a1943f3) +```sh + # run only the tests with "auth user" in the title + $ npx cypress run --env grep="auth user" + # run tests with "hello" or "auth user" in their titles + # by separating them with ";" character + $ npx cypress run --env grep="hello; auth user" +``` +To really target specific tests, add `--spec ...` argument + +```sh + $ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" + \ --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +``` +**Repeat and burn tests** + +You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in the spec A five times using: + +```sh + $ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +``` + + +**Formatting and Linting:** + +Launch the linter. To attempt to automatically fix any errors found, use `npm run lint:fix` + +```sh +# root project directory +npm run lint +# Find and fix linting errors automatically +npm run lint:fix +``` + +Launch the prettier formatter. We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [LINK TO REPO](#) -## Local development environment +```sh +# root project directory +npm run format +``` + +

(back to top)

+ + + + + +### Running the project Locally A containerized environment, oriented to local development, is available to be run from the repository. @@ -125,69 +352,97 @@ This environment is intended for locally testing any functionality that requires There is an Nginx reverse proxy container on top of the frontend and backend containers to avoid CORS issues while testing the application. -### Run the environment + + +**Run the environment** + +```sh +# /dev-env/ directory ./run-env.sh ``` - As the script argument, add the name of the Dataverse image tag you want to deploy. Note that the image tag in the docker registry must to be pre pushed, otherwise the script will fail. -If you are running the script for the first time, it may take a while, since `npm install` has to install all the dependencies. This can also happen if you added new dependencies to package.json. +If you are running the script for the first time, it may take a while, since npm install has to install all the dependencies. This can also happen if you added new dependencies to package.json. Once the script has finished, you will be able to access Dataverse via: -- [http://localhost:8000/spa](http://localhost:8000/spa): SPA Frontend -- [http://localhost:8000](http://localhost:8000): Dataverse Backend and JSF Frontend +[http://localhost:8000/spa](http://localhost:8000/spa): SPA Frontend +[http://localhost:8000](http://localhost:8000): Dataverse Backend and JSF Frontend -_Note: The Dataverse configbaker takes some time to start the application, so the application will not be accessible until the bootstrapping is complete._ +Note: The Dataverse configbaker takes some time to start the application, so the application will not be accessible until the bootstrapping is complete. +**Adding custom test data** If you want to add test data (collections and datasets) to the Dataverse instance, run the following command: -``` +```sh +# /dev-env/ directory ./add-env-data.sh ``` +Note: The above command uses the dataverse-sample-data repository whose scripts occasionally fail, so some of the test data may not be added. -_Note: The above command uses the dataverse-sample-data repository whose scripts occasionally fail, so some of the test data may not be added_ - -### Remove the environment + + +### Deployment -Once the site is built through the `npm run build` command, it can be deployed in different ways to different types of infrastructure, depending on installation needs. +Once the site is built through the **`npm run build`** command, it can be deployed in different ways to different types of infrastructure, depending on installation needs. We are working to provide different preconfigured automated deployment options, seeking to support common use cases today for installing applications of this nature. -The current automated deployment options are available within the GitHub `deploy` workflow, which is designed to be run manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment. +The current automated deployment options are available within the GitHub **`deploy`** workflow, which is designed to be run manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment. + +#### Examples of deployment environments -### AWS S3 Deployment +
+AWS S3 Deployment This option will build and deploy the application to a remote S3 bucket. For this workflow to work, a GitHub environment must be configured with the following environment secrets: -- AWS_ACCESS_KEY_ID -- AWS_SECRET_ACCESS_KEY -- AWS_S3_BUCKET_NAME -- AWS_DEFAULT_REGION + - AWS_ACCESS_KEY_ID + - AWS_SECRET_ACCESS_KEY + - AWS_S3_BUCKET_NAME + - AWS_DEFAULT_REGION Note that for the deployment to the S3 bucket to succeed, you must make the following changes to the bucket via the S3 web interface (or equivalent changes using aws-cli or similar tools): -- Under "Permissions", "Permissions overview", "Block public access (bucket settings)", click "Edit", then uncheck "Block all public access" and save. -- Under "Properties", "Static website hosting", click "Edit" and enable it. Change "Index document" and "Error document" to "index.html". -- Under "Bucket policy", click "Edit" and paste the following policy (changing `` to your bucket name) and save. + - Under "Permissions", "Permissions overview", "Block public access (bucket settings)", click "Edit", then uncheck "Block all public access" and save. + - Under "Properties", "Static website hosting", click "Edit" and enable it. Change "Index document" and "Error document" to "index.html". + - Under "Bucket policy", click "Edit" and paste the following policy (changing to your bucket name) and save. -``` +```json { "Version": "2012-10-17", "Statement": [ @@ -205,10 +460,12 @@ Note that for the deployment to the S3 bucket to succeed, you must make the foll ] } ``` +You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; `http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` -You should see the deployed app at http://BUCKET-NAME.s3-website-REGION.amazonaws.com such as http://mybucket.s3-website-us-east-1.amazonaws.com +
-### Payara Deployment +
+Payara Deployment This option will build and deploy the application to a remote Payara server. @@ -216,15 +473,39 @@ This option is intended for an "all-in-one" solution, where the Dataverse backen For this workflow to work, a GitHub environment must be configured with the following environment secrets: -- PAYARA_INSTANCE_HOST -- PAYARA_INSTANCE_USERNAME -- PAYARA_INSTANCE_SSH_PRIVATE_KEY + - PAYARA_INSTANCE_HOST + - PAYARA_INSTANCE_USERNAME + - PAYARA_INSTANCE_SSH_PRIVATE_KEY It is important that the remote instance is correctly pre-configured, with the Payara server running, and a service account for Dataverse with the corresponding SSH key pair established. A base path for the frontend application can be established on the remote server by setting the corresponding field in the workflow inputs. This mechanism prevents conflicts between the frontend application and any pre-existing deployed application running on Payara, which can potentially be a Dataverse backend. This way, only the routes with the base path included will redirect to the frontend application. -#### Beta Testing Environment +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "PublicReadGetObject", + "Principal": "*", + "Effect": "Allow", + "Action": [ + "s3:GetObject" + ], + "Resource": [ + "arn:aws:s3:::/*" + ] + } + ] +} +``` +You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; `http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` + +
+ +### Beta Testing Environment + +_Easily set up a local development environment!_ To make the SPA Frontend accesible and testable by people interested in the project, there is a remote beta testing environment that includes the latest changes developed both for the frontend application and the Dataverse backend application (develop branches). @@ -234,41 +515,229 @@ Environment updates are carried out automatically through GitHub actions, presen The environment is accessible through the following URLs: -- SPA: https://beta.dataverse.org/spa -- JSF: https://beta.dataverse.org + - SPA: https://beta.dataverse.org/spa + - JSF: https://beta.dataverse.org -## Changes from the original JSF application + -### Changes from the Style Guide +## Usage -The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. +Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. -#### Links +_For more examples, please refer to the [Documentation](https://guides.dataverse.org/en/latest/developers/index.html)_ -We added an underline to links to make them accessible. +

(back to top)

-#### File label + -Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies -the secondary color to the labels automatically, the color of the file label is now the global secondary color which is -a lighter shade of grey than what it used to be. +## Components -We changed the citation block to be white with a colored border, to make the text in the box more accessible. + -### Changes in functionality behavior +## Code -Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. + -#### Dataset files tab search + -The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. + -The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search options are available for all versions in the same way, homogenizing behavior, although losing the possibility of using the Solr grammar. + -The decision of this change is made on the assumption that Solr may not be required in the context of files tab search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that the assumption is incorrect, we will work on extending the search capabilities to support Solr. +## Roadmap + + + +- [ ] Add Changelog +- [ ] Add back to top links +- [ ] Add Additional Templates w/ Examples +- [ ] Add "components" document to easily copy & paste sections of the readme + + +See the [open issues](https://github.com/IQSS/dataverse-frontend/issues) for a full list of proposed features (and known issues). + +

(back to top)

+ + + +## Contributing + +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. + +If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". + +We love PRs! Read the Contributor Guidelines for more info. Say hello, share your tips/work, and spread the love on + +

(back to top)

+ + + + + + -## Thanks +## License + +Distributed under the Apache License, Version 2.0. See `LICENSE` for more information. + +

(back to top)

+ + + +## Contact + +Email us with software installation questions. Please note our response time is generally 24 business hours. + + + +### For developers and Dataverse Repositories + +Report issues and contribute to our code: Report bugs and add feature requests in GitHub Issues or use GitHub pull requests, if you have some code, scripts or documentation that you'd like to share. If you have a security issue to report, please email security@dataverse.org. + +Ask a question or start a discussion: A great place to publicly share feedback, ideas, feature requests, and troubleshoot any issues is in the dataverse-community mailing list. Additional mailing lists are available, including language-specific ones. + +Chat with us at chat.dataverse.org. + +Your Name - [@your_twitter](https://twitter.com/your_username) - email@example.com + +Project Link: [https://github.com/your_username/repo_name](https://github.com/your_username/repo_name) + +

(back to top)

+ + + +## Acknowledgments + +Use this space to list resources you find helpful and would like to give credit to. I've included a few of my favorites to kick things off! + +- [Img Shields](https://shields.io) Chromatic Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions. + +

(back to top)

+ +### Built With + +This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples. + + + + + + + + + +

(back to top)

+ + + + + +[![Node][Node.js]][Node-url] + +[Node.js]: https://img.shields.io/badge/node.js-000000?style=for-the-badge&logo=nodedotjs&logoColor=white +[Node-url]: https://nodejs.org/ + + + +[![React][React.js]][React-url] + +[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB +[React-url]: https://reactjs.org/ + + + +[![TypeScript][TypeScript]][Typescript-url] + +[TypeScript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white +[Typescript-url]: https://typescriptlang.org/ + + + +[![Bootstrap][Bootstrap.com]][Bootstrap-url] + +[Bootstrap.com]: https://img.shields.io/badge/Bootstrap-563D7C?style=for-the-badge&logo=bootstrap&logoColor=white +[Bootstrap-url]: https://getbootstrap.com + + + +[![Cypress][Cypress.io]][Cypress-url] + +[Cypress.io]: https://img.shields.io/badge/Cypress-69D3A7?style=for-the-badge&logo=cypress&logoColor=black +[Cypress-url]: https://cypress.io/ + + + +[![TestingLibrary][TestingLibrary]][TestingLibrary-url] + +[TestingLibrary]: https://img.shields.io/badge/TestingLibrary-E33332?style=for-the-badge&logo=testinglibrary&logoColor=white +[TestingLibrary-url]: https://svelte.dev/ + + + +[![Storybook][Storybook.com]][Storybook-url] + +[Storybook.com]: https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white +[Storybook-url]: https://laravel.com + + + +[![GH-Contributors][GH-Contributors-shield]][GH-Contributors-url] + +[GH-Contributors-shield]: https://img.shields.io/github/contributors/IQSS/dataverse-frontend?branch=develop&style=for-the-badge +[GH-Contributors-url]: https://github.com/IQSS/dataverse-frontend/graphs/contributors + + + +[![Coveralls Coverage][Coveralls-badge]][Coveralls-url] + +[Coveralls-badge]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge&logo=coveralls +[Coveralls-url]: https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop + + + +[![WorkflowStatus][Workflow-badge]][Workflow-url] + +[Workflow-badge]: https://img.shields.io/github/actions/workflow/status/IQSS/dataverse-frontend/test.yml?branch=develop&style=for-the-badge +[Workflow-url]: https://github.com/IQSS/dataverse-frontend/actions + + + +![GitHub forks](https://img.shields.io/github/forks/IQSS/dataverse-frontend?style=for-the-badge) + + + +![GitHub Tag](https://img.shields.io/github/v/tag/iqss/dataverse-frontend?style=for-the-badge) + + + +[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.][RepoStatus-badge]][RepoStatus-url] + +[RepoStatus-badge]: https://img.shields.io/badge/repo_status-WIP-yellow?style=for-the-badge +[RepoStatus-url]: https://www.repostatus.org/#wip + +[![TestsStatus][TestsStatus-badge]][TestsStatus-url] + +[TestsStatus-badge]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml/badge.svg +[TestsStatus-url]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml + + + + +[![Stargazers][stars-badge]][stars-url] + +[stars-badge]: https://img.shields.io/github/stars/iqss/dataverse-frontend?style=for-the-badge +[stars-url]: https://github.com/IQSS/dataverse-frontend/stargazers + + + +[![Open issues][issue-badge]][issue-url] + +[issue-badge]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge +[issue-url]: https://github.com/IQSS/dataverse-frontend/issues + +[product-screenshot]: images/screenshot.png + From efdc807e8400b7bb2a92c7025755bd47e5eb1286 Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Wed, 28 Feb 2024 17:01:29 -0500 Subject: [PATCH 02/26] Readme Formatting --- README.md | 237 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 147 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index c2cf9fc2d..470ce0768 100644 --- a/README.md +++ b/README.md @@ -28,14 +28,14 @@

Dataverse Frontend

- _Tagline_ + A New Way To Create and View Datasets & Collections!
Explore the docs »

- View Demo· - Report Bug· - Request Feature. + View Demo (BETA)· + Report Bug· + Request Feature.

@@ -46,31 +46,28 @@
  • About The Project
  • Getting Started
    • -
  • Additional Configurations +
  • Deployment
    • -
  • Development
    • -
  • Components
    • -
  • Code
  • Usage
    • +
  • Components
    • +
  • Code
  • Roadmap
  • Contributing
  • License
    • @@ -98,7 +95,8 @@ The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [![Dataverse Website][dataverse-web-link]](https://dataverse.org/about) -### What is Dataverse Frontend & How do they differ? +### What is Dataverse Frontend? +__**& How do they differ?**__ The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations and utilize the JavaScript framework of their choice. @@ -123,15 +121,30 @@ The Dataverse Frontend repository is an initiative undertaken in 2023 to moderni - Cypress testing automation - Storybook for UI Component Library + +### Beta Testing Environment + +_Track our progress and compare it to the current Dataverse application!_ + +To make the SPA Frontend accesible and testable by people interested in the project, there is a remote beta testing environment that includes the latest changes developed both for the frontend application and the Dataverse backend application (develop branches). + +This environment follows the "all-in-one" solution described above, where both applications coexist on a Payara server. + +Environment updates are carried out automatically through GitHub actions, present both in this repository and in the Dataverse backend repository, which deploy the develop branches when any change is pushed to them. + +The environment is accessible through the following URLs: + + - Dataverse Frontend SPA @ [beta.dataverse.org/spa](https://beta.dataverse.org/spa) + - Dataverse JSF @ [beta.dataverse.org](https://beta.dataverse.org) + + ### How existing Dataverse installations may be affected - The existing Dataverse API will be added to and extended from the present backend architecture while the existing UI and current Dataverse functionalities are preserved. - The SPA will continue its life as a separate application, supported on its own maintenance schedule. - When the SPA has matured enough for an official release, we will switch to the new version and the old backend (Link to repository) will be moved into maintenance mode with no new features being introduced and focusing only on critical bugfixes. - - -#### Changes from the original JSF application +#### Changes from the original Dataverse JSF application
    Expand @@ -174,12 +187,12 @@ The decision of this change is made on the assumption that Solr may not be requi -To get a local copy up and running follow these simple example steps. +_To get a local copy up and running follow these simple example steps._ ### Prerequisites 1. Node **node >=16** and NPM **npm >=8**. Recommended versions for this project are `node v19` and `npm v9`. -1. Docker. We use [![DockerDesktop][DockerBadge]][Docker-url]. +1. Docker. We use Docker Desktop, but the Docker CLI will also work! [![DockerDesktop][DockerDesktop-badge]][DockerDesktop-url]. 1. Add your NPM and GitHub Tokens. In order to connect with the Dataverse API, develoeprs will need to install [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) from the GitHub registry by following the steps outlined below: 1. Navigate to the project directory root and duplicate the `.npmrc.example` file, saving the copy as `.npmrc`. @@ -422,25 +435,25 @@ We are working to provide different preconfigured automated deployment options, The current automated deployment options are available within the GitHub **`deploy`** workflow, which is designed to be run manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment. -#### Examples of deployment environments +#### Examples for AWS and Payara
    -AWS S3 Deployment +AWS S3 Deployment [Expand] This option will build and deploy the application to a remote S3 bucket. For this workflow to work, a GitHub environment must be configured with the following environment secrets: - - AWS_ACCESS_KEY_ID - - AWS_SECRET_ACCESS_KEY - - AWS_S3_BUCKET_NAME - - AWS_DEFAULT_REGION + - `AWS_ACCESS_KEY_ID` + - `AWS_SECRET_ACCESS_KEY` + - `AWS_S3_BUCKET_NAME` + - `AWS_DEFAULT_REGION` Note that for the deployment to the S3 bucket to succeed, you must make the following changes to the bucket via the S3 web interface (or equivalent changes using aws-cli or similar tools): - Under "Permissions", "Permissions overview", "Block public access (bucket settings)", click "Edit", then uncheck "Block all public access" and save. - Under "Properties", "Static website hosting", click "Edit" and enable it. Change "Index document" and "Error document" to "index.html". - - Under "Bucket policy", click "Edit" and paste the following policy (changing to your bucket name) and save. + - Under "Bucket policy", click "Edit" and paste the following policy (changing `` to your bucket name) and save. ```json { @@ -465,7 +478,7 @@ You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].ama
    -Payara Deployment +Payara Deployment [Expand] This option will build and deploy the application to a remote Payara server. @@ -473,50 +486,16 @@ This option is intended for an "all-in-one" solution, where the Dataverse backen For this workflow to work, a GitHub environment must be configured with the following environment secrets: - - PAYARA_INSTANCE_HOST - - PAYARA_INSTANCE_USERNAME - - PAYARA_INSTANCE_SSH_PRIVATE_KEY + - `PAYARA_INSTANCE_HOST` + - `PAYARA_INSTANCE_USERNAME` + - `PAYARA_INSTANCE_SSH_PRIVATE_KEY` It is important that the remote instance is correctly pre-configured, with the Payara server running, and a service account for Dataverse with the corresponding SSH key pair established. A base path for the frontend application can be established on the remote server by setting the corresponding field in the workflow inputs. This mechanism prevents conflicts between the frontend application and any pre-existing deployed application running on Payara, which can potentially be a Dataverse backend. This way, only the routes with the base path included will redirect to the frontend application. -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "PublicReadGetObject", - "Principal": "*", - "Effect": "Allow", - "Action": [ - "s3:GetObject" - ], - "Resource": [ - "arn:aws:s3:::/*" - ] - } - ] -} -``` -You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; `http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` -
    -### Beta Testing Environment - -_Easily set up a local development environment!_ - -To make the SPA Frontend accesible and testable by people interested in the project, there is a remote beta testing environment that includes the latest changes developed both for the frontend application and the Dataverse backend application (develop branches). - -This environment follows the "all-in-one" solution described above, where both applications coexist on a Payara server. - -Environment updates are carried out automatically through GitHub actions, present both in this repository and in the Dataverse backend repository, which deploy the develop branches when any change is pushed to them. - -The environment is accessible through the following URLs: - - - SPA: https://beta.dataverse.org/spa - - JSF: https://beta.dataverse.org @@ -528,30 +507,24 @@ _For more examples, please refer to the [Documentation](https://guides.dataverse

    (back to top)

    - - -## Components - - + -## Code + - + - + - + ## Roadmap - - - [ ] Add Changelog -- [ ] Add back to top links - [ ] Add Additional Templates w/ Examples -- [ ] Add "components" document to easily copy & paste sections of the readme +- [ ] Add "Components" document to easily copy & paste sections of the readme +- [ ] More... See the [open issues](https://github.com/IQSS/dataverse-frontend/issues) for a full list of proposed features (and known issues). @@ -566,13 +539,13 @@ Contributions are what make the open source community such an amazing place to l If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". -We love PRs! Read the Contributor Guidelines for more info. Say hello, share your tips/work, and spread the love on +We love PRs! Read the Contributor Guidelines for more info. Say hello, share your tips/work, and spread the love on ...

    (back to top)

    - + - + @@ -588,7 +561,7 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform Email us with software installation questions. Please note our response time is generally 24 business hours. - + ### For developers and Dataverse Repositories @@ -600,7 +573,7 @@ Chat with us at chat.dataverse.org. Your Name - [@your_twitter](https://twitter.com/your_username) - email@example.com -Project Link: [https://github.com/your_username/repo_name](https://github.com/your_username/repo_name) +Project Link: [https://github.com/IQSS/dataverse-frontend](https://github.com/IQSS/dataverse-frontend)

    (back to top)

    @@ -608,10 +581,6 @@ Project Link: [https://github.com/your_username/repo_name](https://github.com/yo ## Acknowledgments -Use this space to list resources you find helpful and would like to give credit to. I've included a few of my favorites to kick things off! - -- [Img Shields](https://shields.io) - Chromatic Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions. @@ -739,5 +708,93 @@ This section should list any major frameworks/libraries used to bootstrap your p [issue-badge]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge [issue-url]: https://github.com/IQSS/dataverse-frontend/issues + + +[DockerDesktop-badge]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white +[DockerDesktop-url]: https://www.docker.com/products/docker-desktop/ + + +[AmazonS3-badge]: https://img.shields.io/badge/AmazonS3-569A31?style=for-the-badge&logo=amazons3&logoColor=white +[AmazonS3-url]: https://aws.amazon.com/ + +[Payara-url]: https://www.payara.fish/ + + + [product-screenshot]: images/screenshot.png + + + + +[forks-shield]: https://img.shields.io/github/forks/othneildrew/Best-README-Template.svg?style=for-the-badge +[forks-url]: https://github.com/othneildrew/Best-README-Template/network/members +[stars-shield]: https://img.shields.io/github/stars/othneildrew/Best-README-Template.svg?style=for-the-badge +[stars-url]: https://github.com/othneildrew/Best-README-Template/stargazers +[license-shield]: https://img.shields.io/github/license/othneildrew/Best-README-Template.svg?style=for-the-badge +[license-url]: https://github.com/othneildrew/Best-README-Template/blob/master/LICENSE.txt +[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 +[linkedin-url]: https://linkedin.com/in/othneildrew +[JQuery.com]: https://img.shields.io/badge/jQuery-0769AD?style=for-the-badge&logo=jquery&logoColor=white +[JQuery-url]: https://jquery.com + + + +[npm-url]: https://www.npmjs.com/package/react-parallax-tilt +[npm-badge]: https://img.shields.io/npm/v/react-parallax-tilt.svg +[size-url]: https://bundlephobia.com/package/react-parallax-tilt +[size-badge]: https://badgen.net/bundlephobia/minzip/react-parallax-tilt +[downloads-badge]: https://img.shields.io/npm/dm/react-parallax-tilt.svg?color=blue +[lint-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/lint.yml/badge.svg +[lint-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/lint.yml +[tsc-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/tsc.yml/badge.svg +[tsc-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/tsc.yml +[build-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/build.yml/badge.svg +[build-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/build.yml +[test-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/test.yml/badge.svg +[test-url]: https://react-parallax-tilt-test-unit-report.netlify.app/ +[test-e2e-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/test-e2e.yml/badge.svg +[test-e2e-url]: https://react-parallax-tilt-test-e2e-report.netlify.app/ +[deploy-storybook-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/deploy-storybook.yml/badge.svg +[deploy-storybook-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/deploy-storybook.yml +[npm-release-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/npm-release.yml/badge.svg +[npm-release-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/npm-release.yml +[semantic-badge]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg +[semantic-url]: https://github.com/semantic-release/semantic-release + + + + + + + + + + + + + + + + + + + + + From 727deba5171673a7c96faba113e15f12fa06cb8b Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Thu, 29 Feb 2024 17:03:07 -0500 Subject: [PATCH 03/26] More readme updates --- README.md | 159 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 84 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 470ce0768..327645d35 100644 --- a/README.md +++ b/README.md @@ -88,15 +88,15 @@ ### Demo videos -- 2023-08-01: [View mode of the dataset page](https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ) -- 2023-12-13: [Files table on the dataset page](https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ) +- [Dataset Page General Overview](https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ) (August, 2023) +- [Dataset Page Files Table](https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ) (December, 2023) ### What is Dataverse? The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [![Dataverse Website][dataverse-web-link]](https://dataverse.org/about) ### What is Dataverse Frontend? -__**& How do they differ?**__ +_& How do they differ?_ The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations and utilize the JavaScript framework of their choice. @@ -134,8 +134,8 @@ Environment updates are carried out automatically through GitHub actions, presen The environment is accessible through the following URLs: - - Dataverse Frontend SPA @ [beta.dataverse.org/spa](https://beta.dataverse.org/spa) - - Dataverse JSF @ [beta.dataverse.org](https://beta.dataverse.org) + - Dataverse Frontend SPA: [beta.dataverse.org/spa](https://beta.dataverse.org/spa) + - Dataverse JSF: [beta.dataverse.org](https://beta.dataverse.org) ### How existing Dataverse installations may be affected @@ -190,30 +190,32 @@ The decision of this change is made on the assumption that Solr may not be requi _To get a local copy up and running follow these simple example steps._ ### Prerequisites +[![DockerDesktop][DockerDesktop-badge]][DockerDesktop-url] 1. Node **node >=16** and NPM **npm >=8**. Recommended versions for this project are `node v19` and `npm v9`. -1. Docker. We use Docker Desktop, but the Docker CLI will also work! [![DockerDesktop][DockerDesktop-badge]][DockerDesktop-url]. - -1. Add your NPM and GitHub Tokens. In order to connect with the Dataverse API, develoeprs will need to install [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) from the GitHub registry by following the steps outlined below: -1. Navigate to the project directory root and duplicate the `.npmrc.example` file, saving the copy as `.npmrc`. - > ```sh - > # root project directory - > cp .npmrc.example .npmrc - > ``` -1. Follow the steps outlined below to generate a [personal access token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) used to interface with the GitHub API. - -> 1. Getting a GitHub token -> 1. Go to your GitHub **[Personal Access Tokens](https://github.com/settings/tokens)** settings -> 2. Select **_Generate new token (classic)_** -> 3. Give the token a name and select scope **_`read:packages`_** -> 4. Copy the generated token and replace the string _**`YOUR_GITHUB_AUTH_TOKEN`**_ in the **_`.npmrc`_** file in the project base. -> Now, you should be able to install the [Dataverse JavaScript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) client using npm. - -```plaintext -legacy-peer-deps=true +2. Docker! We use Docker Desktop, but the Docker CLI will also work! +3. Add your NPM and GitHub Tokens. In order to connect with the Dataverse API, develoeprs will need to install [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) from the GitHub registry by following the steps outlined below: +4. Navigate to the project directory root and duplicate the `.npmrc.example` file, saving the copy as `.npmrc`. + > ```sh + > # root project directory + > cp .npmrc.example .npmrc + > ``` +5. Follow the steps outlined below to generate a personal access token used to interface with the GitHub API. Read more about access tokens on [GitHub Docs](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + + > __Getting a GitHub token__ + > 1. Go to your GitHub **[Personal Access Tokens](https://github.com/settings/tokens)** settings + > 2. Select **_Generate new token (classic)_** + > 3. Give the token a name and select scope **_`read:packages`_** + > 4. Copy the generated token and replace the string _**`YOUR_GITHUB_AUTH_TOKEN`**_ in the **_`.npmrc`_** file in the project base. + > Now, you should be able to install the [Dataverse JavaScript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) client using npm. + +```properties +# .npmrc - //npm.pkg.github.com/:_authToken= - @iqss:registry=https://npm.pkg.github.com/ +legacy-peer-deps=true +# js-dataverse registry +//npm.pkg.github.com/:_authToken= +@iqss:registry=https://npm.pkg.github.com/ ``` ### Installation & Setup @@ -234,10 +236,12 @@ Please check this announcement from Create React App repository [facebook/create 2. Build the UI Library, needed for running the application. ```sh - cd packages/design-system && npm run build +# root project directory +cd packages/design-system && npm run build ``` -#### Additional scrips available +### Additional scrips available + **Running & building the app:** @@ -263,23 +267,30 @@ npm run preview Runs the Storybook in the development mode. -There are 2 Storybook instances, one for the general Design System and one for the Dataverse Frontend component specifications. +There are 2 Storybook instances, one for the general Design System and one for the Dataverse Frontend component specifications. Both should be started automatically and available at: +- Dataverse Frontend Storybook: [http://localhost:6006/](http://localhost:6006/) +- Dataverse Design System Storybook: [http://localhost:6007/](http://localhost:6007/) ```sh # $ cd packages/design-system -npm run [build-]storybook +npm run storybook + +# 'npm run storybook` should automatically open in your default browser + +# $ cd packages/design-system +npm run build-storybook -# 'npm run storybook` should automatically open the following urls in your default browser -# Dataverse Frontend Storybook at: http://localhost:6006/ -# Dataverse Design System Storybook at: http://localhost:6007/ ``` + Note that both Storybook instances are also published to Chromatic as part of the build and merge processes, located at: [![DataverseFrontend][DataverseFrontend-Chromatic]][DataverseFrontend-Chromatic-url] + [![DataverseDesignSystem][DataverseDesignSystem-Chromatic]][DataverseDesignSystem-Chromatic-url] + **Run the environment** +As the script argument, add the name of the Dataverse image tag you want to deploy. ```sh # /dev-env/ directory -./run-env.sh -``` -As the script argument, add the name of the Dataverse image tag you want to deploy. -Note that the image tag in the docker registry must to be pre pushed, otherwise the script will fail. +# Installs and runs project off latest tagged container image +$ ./run-env.sh -If you are running the script for the first time, it may take a while, since npm install has to install all the dependencies. This can also happen if you added new dependencies to package.json. +# Removes ... +$ ./rm-env.sh +``` +Note that the image tag in the docker registry must to be pre pushed, otherwise the script will fail. You can find the existing tags on DockerHub [@gdcc/dataverse](https://hub.docker.com/r/gdcc/dataverse/tags) + +If you are running the script for the first time, it may take a while, since npm has to install all project dependencies. This can also happen if you added new dependencies to `package.json`, or used the _uninstall_ script to remove current project files and shut down any running containers. Once the script has finished, you will be able to access Dataverse via: -[http://localhost:8000/spa](http://localhost:8000/spa): SPA Frontend -[http://localhost:8000](http://localhost:8000): Dataverse Backend and JSF Frontend +- Dataverse SPA Frontend: [http://localhost:8000/spa](http://localhost:8000/spa) +- Dataverse JSF Application: [http://localhost:8000](http://localhost:8000) Note: The Dataverse configbaker takes some time to start the application, so the application will not be accessible until the bootstrapping is complete. @@ -401,31 +424,17 @@ If you want to add test data (collections and datasets) to the Dataverse instanc ```sh # /dev-env/ directory -./add-env-data.sh +$ ./add-env-data.sh ``` -Note: The above command uses the dataverse-sample-data repository whose scripts occasionally fail, so some of the test data may not be added. +Note: The above command uses the [dataverse-sample-data](https://github.com/IQSS/dataverse-sample-data) repository whose scripts occasionally fail, so some of the test data may not be added. +
    +--> ### Deployment @@ -451,7 +460,7 @@ For this workflow to work, a GitHub environment must be configured with the foll Note that for the deployment to the S3 bucket to succeed, you must make the following changes to the bucket via the S3 web interface (or equivalent changes using aws-cli or similar tools): - - Under "Permissions", "Permissions overview", "Block public access (bucket settings)", click "Edit", then uncheck "Block all public access" and save. + - Under "_Permissions_", "_Permissions overview_", "_Block public access (bucket settings)_", click "_Edit_", then __uncheck__ "_Block all public access_" and save. - Under "Properties", "Static website hosting", click "Edit" and enable it. Change "Index document" and "Error document" to "index.html". - Under "Bucket policy", click "Edit" and paste the following policy (changing `` to your bucket name) and save. @@ -537,7 +546,7 @@ See the [open issues](https://github.com/IQSS/dataverse-frontend/issues) for a f Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. -If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". +If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "`enhancement`". We love PRs! Read the Contributor Guidelines for more info. Say hello, share your tips/work, and spread the love on ... From 94ba94133cb9547f2a26b45f94e40d81b1d9135f Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Fri, 1 Mar 2024 15:26:49 -0500 Subject: [PATCH 04/26] test codeblock formatting --- README.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 327645d35..d65aeac57 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,7 @@ _To get a local copy up and running follow these simple example steps._ > 4. Copy the generated token and replace the string _**`YOUR_GITHUB_AUTH_TOKEN`**_ in the **_`.npmrc`_** file in the project base. > Now, you should be able to install the [Dataverse JavaScript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) client using npm. -```properties +```npmrc # .npmrc legacy-peer-deps=true @@ -228,10 +228,14 @@ _Below is an example of how you can instruct your audience on installing and set # root project directory npm install ``` +> [!WARNING] +> You may see a message about vulnerabilities after running this command. +> +> Please check this announcement from Create React App repository [facebook/create-react-app#11174](https://github.com/facebook/create-react-app/issues/11174). These vulnerabilities will not be included in the production build since they come from libraries only used during development. + + -You may see a message about vulnerabilities after running this command. -Please check this announcement from Create React App repository [facebook/create-react-app#11174](https://github.com/facebook/create-react-app/issues/11174). These vulnerabilities will not be included in the production build since they come from libraries only used during development. 2. Build the UI Library, needed for running the application. @@ -611,7 +615,7 @@ This section should list any major frameworks/libraries used to bootstrap your p

    (back to top)

    - +
    [![Node][Node.js]][Node-url] @@ -633,6 +637,7 @@ This section should list any major frameworks/libraries used to bootstrap your p [TypeScript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white [Typescript-url]: https://typescriptlang.org/ +
    [![Bootstrap][Bootstrap.com]][Bootstrap-url] @@ -807,3 +812,12 @@ This section should list any major frameworks/libraries used to bootstrap your p + + + + + + + + +*** \ No newline at end of file From af3e426c16a0bfc1d95b6d9abb179af22f394d36 Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Tue, 5 Mar 2024 10:50:39 -0500 Subject: [PATCH 05/26] formatting, links, logo tests --- README.md | 633 ++++++++++++++++++++++++------------------------------ 1 file changed, 282 insertions(+), 351 deletions(-) diff --git a/README.md b/README.md index d65aeac57..856004c9f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,6 @@ - - + + + +
    - Logo + Logo + Logo -

    Dataverse Frontend

    +

    Dataverse Frontend

    A New Way To Create and View Datasets & Collections!
    Explore the docs »

    - View Demo (BETA)· - Report Bug· - Request Feature. + Website | + View Demo (BETA) | + Report Bug | + Request Feature

    +
    +

    Progress Demo Videos

    +

    + Dataset Overview Page (Aug. '23) | + Dataset Files Table (Dec. '23) +

    +--- + +### ⚠️ Important information about the Dataverse Frontend ⚠️ +> Dataverse Frontend is currently in beta and under active development. While it offers exciting new features, please note that it may not be stable for production use. We recommend sticking to the latest stable [Dataverse][dv_repo_legacyjsf_url] release for mission-critical applications. If you choose to use this repository in production, be prepared for potential bugs and breaking changes. Always check the official documentation and release notes for updates and proceed with caution. + +For more information and a list of additional resources, please visit this [discussion](#). + +--- +
    Table of Contents @@ -80,26 +99,23 @@ ## About The Project -[![Product Name Screen Shot][product-screenshot]](https://example.com) - - +[![Product Name Screen Shot][_img_screenshot]][_img_screenshot] --- -### Demo videos - -- [Dataset Page General Overview](https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ) (August, 2023) -- [Dataset Page Files Table](https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ) (December, 2023) - ### What is Dataverse? -The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [![Dataverse Website][dataverse-web-link]](https://dataverse.org/about) +The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [Dataverse Website][dv_docs_dataverse_url] + +
    + -### What is Dataverse Frontend? -_& How do they differ?_ +### What is Dataverse Frontend _& How do they differ?_ The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations and utilize the JavaScript framework of their choice. +
    + **The goals of Dataverse Frontend:** - Modernize the application @@ -121,6 +137,8 @@ The Dataverse Frontend repository is an initiative undertaken in 2023 to moderni - Cypress testing automation - Storybook for UI Component Library +
    +*** ### Beta Testing Environment @@ -134,8 +152,8 @@ Environment updates are carried out automatically through GitHub actions, presen The environment is accessible through the following URLs: - - Dataverse Frontend SPA: [beta.dataverse.org/spa](https://beta.dataverse.org/spa) - - Dataverse JSF: [beta.dataverse.org](https://beta.dataverse.org) + - Dataverse Frontend SPA: [beta.dataverse.org/spa][dv_app_beta_spa_url] + - Dataverse JSF: [beta.dataverse.org][dv_app_beta_legacyjsf_url] ### How existing Dataverse installations may be affected @@ -144,72 +162,71 @@ The environment is accessible through the following URLs: - The SPA will continue its life as a separate application, supported on its own maintenance schedule. - When the SPA has matured enough for an official release, we will switch to the new version and the old backend (Link to repository) will be moved into maintenance mode with no new features being introduced and focusing only on critical bugfixes. -#### Changes from the original Dataverse JSF application
    -Expand - -##### Changes from the Style Guide - -The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. - -###### Links - -We added an underline to links to make them accessible. - -###### File label - -Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies -the secondary color to the labels automatically, the color of the file label is now the global secondary color which is -a lighter shade of grey than what it used to be. - -We changed the citation block to be white with a colored border, to make the text in the box more accessible. - -##### Changes in functionality behavior - -Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. - -###### Dataset files tab search - -The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. - -The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search options are available for all versions in the same way, homogenizing behavior, although losing the possibility of using the Solr grammar. - -The decision of this change is made on the assumption that Solr may not be required in the context of files tab search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that the assumption is incorrect, we will work on extending the search capabilities to support Solr. + Changes from the original Dataverse JSF application + + + >##### Changes from the Style Guide + > + >The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. + > + >###### Links + > + >We added an underline to links to make them accessible. + > + >###### File label + > + >Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies + the secondary color to the labels automatically, the color of the file label is now the global secondary color which is + a lighter shade of grey than what it used to be. + > + >We changed the citation block to be white with a colored border, to make the text in the box more accessible. + > + >##### Changes in functionality behavior + > + >Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. + > + >###### Dataset files tab search + > + >The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. + > + >The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search options are available for all versions in the same way, homogenizing behavior, although losing the possibility of using the Solr grammar. + > + >The decision of this change is made on the assumption that Solr may not be required in the context of files tab search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that the assumption is incorrect, we will work on extending the search capabilities to support Solr.

    (back to top)

    - +
    +*** ## Getting Started - - _To get a local copy up and running follow these simple example steps._ ### Prerequisites -[![DockerDesktop][DockerDesktop-badge]][DockerDesktop-url] +[![DockerDesktop][_shield_docker]][_uses_docker_url-url] -1. Node **node >=16** and NPM **npm >=8**. Recommended versions for this project are `node v19` and `npm v9`. -2. Docker! We use Docker Desktop, but the Docker CLI will also work! -3. Add your NPM and GitHub Tokens. In order to connect with the Dataverse API, develoeprs will need to install [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) from the GitHub registry by following the steps outlined below: -4. Navigate to the project directory root and duplicate the `.npmrc.example` file, saving the copy as `.npmrc`. - > ```sh +1. **Node & NPM**: `node >= v16` and `npm >= v8`. Recommended versions for this project are `node v19` and `npm v9`. +2. **Docker**: We use Docker Desktop, but the Docker CLI will also work! +3. **Create and add your NPM and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps outlined below: +4. Navigate to the project directory root and duplicate `.npmrc.example`, saving the copy as `.npmrc`. + > ```bash > # root project directory > cp .npmrc.example .npmrc > ``` -5. Follow the steps outlined below to generate a personal access token used to interface with the GitHub API. Read more about access tokens on [GitHub Docs](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) +5. Follow the steps outlined below to generate a personal access token used to interface with the GitHub API. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url] - > __Getting a GitHub token__ - > 1. Go to your GitHub **[Personal Access Tokens](https://github.com/settings/tokens)** settings - > 2. Select **_Generate new token (classic)_** - > 3. Give the token a name and select scope **_`read:packages`_** - > 4. Copy the generated token and replace the string _**`YOUR_GITHUB_AUTH_TOKEN`**_ in the **_`.npmrc`_** file in the project base. - > Now, you should be able to install the [Dataverse JavaScript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) client using npm. + > **Getting a GitHub token** + > 1. Go to your GitHub [Personal Access Tokens][dv_docs_github_token_url] settings + > 2. Select `Generate new token (classic)` + > 3. Give the token a name and select scope `read:packages` + > 4. Copy the generated token and replace the string `YOUR_GITHUB_AUTH_TOKEN` in the previously created `.npmrc` file. + > Now, you should be able to install the [Dataverse JavaScript][dv_repo_dvclientjs_url] client using npm. -```npmrc +```.npmrc # .npmrc legacy-peer-deps=true @@ -217,6 +234,7 @@ legacy-peer-deps=true //npm.pkg.github.com/:_authToken= @iqss:registry=https://npm.pkg.github.com/ ``` +
    ### Installation & Setup @@ -224,22 +242,19 @@ _Below is an example of how you can instruct your audience on installing and set 1. Install the project & its dependencies -```sh +```bash # root project directory npm install ``` > [!WARNING] > You may see a message about vulnerabilities after running this command. > -> Please check this announcement from Create React App repository [facebook/create-react-app#11174](https://github.com/facebook/create-react-app/issues/11174). These vulnerabilities will not be included in the production build since they come from libraries only used during development. - - - +> Please check this announcement from Create React App repository [facebook/create-react-app#11174][_uses_repo_cra_error_url]. These vulnerabilities will not be included in the production build since they come from libraries only used during development. 2. Build the UI Library, needed for running the application. -```sh +```bash # root project directory cd packages/design-system && npm run build ``` @@ -249,9 +264,9 @@ cd packages/design-system && npm run build **Running & building the app:** -Run the app in the development mode. Open [http://localhost:5173](http://localhost:5173) to view it in your browser. +Run the app in the development mode. Open [http://localhost:5173][dv_app_localhost_build_url] to view it in your browser. -```sh +```bash # root project directory npm start ``` @@ -259,7 +274,7 @@ npm start The application will actively watch the directory for changes and reload when changes are saved. You may also see any existing linting errors in the console. -```sh +```bash # Build the app for production to the `/dist/` directory: npm run build # Locally preview the production build: @@ -272,21 +287,19 @@ npm run preview Runs the Storybook in the development mode. There are 2 Storybook instances, one for the general Design System and one for the Dataverse Frontend component specifications. Both should be started automatically and available at: -- Dataverse Frontend Storybook: [http://localhost:6006/](http://localhost:6006/) -- Dataverse Design System Storybook: [http://localhost:6007/](http://localhost:6007/) +- Dataverse Frontend Storybook: [http://localhost:6006/][dv_app_localhost_storybook_url] +- Dataverse Design System Storybook: [http://localhost:6007/][dv_app_localhost_designsystem_url] -```sh +```bash # $ cd packages/design-system npm run storybook - -# 'npm run storybook` should automatically open in your default browser +# `npm run storybook` should automatically open in your default browser # $ cd packages/design-system npm run build-storybook ``` - Note that both Storybook instances are also published to Chromatic as part of the build and merge processes, located at: [![DataverseFrontend][DataverseFrontend-Chromatic]][DataverseFrontend-Chromatic-url] @@ -297,15 +310,12 @@ Note that both Storybook instances are also published to Chromatic as part of th - **Testing with Cypress:** Use the following commands to ensure your build passes checks for coding standards and coverage: -```sh +```bash # root project directory # Launches the Cypress test runner for the end-to-end [or unit] tests: npm run test:e2e [test:unit] @@ -319,11 +329,11 @@ npm run test:coverage **Using `grep` with Cypress** -The project includes [@cypress/grep](https://www.npmjs.com/package/@cypress/grep) for running specific tests. +The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. Some examples used by the grep library are below for reference: -```sh +```bash # root project directory # run only the tests with "auth user" in the title @@ -333,10 +343,9 @@ $ npx cypress run --env grep="auth user" $ npx cypress run --env grep="hello; auth user" ``` +To target specific tests, add `--spec` argument -To really target specific tests, add `--spec` argument - -```sh +```bash # root project directory $ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" @@ -347,36 +356,35 @@ $ npx cypress run --env grep="loads the restricted files when the user is logged **Repeat and burn tests** You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in the spec A five times using: -```sh +```bash # root project directory $ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx ``` **Formatting and Linting:** + Launch the linter. To attempt to automatically fix any errors found, use `npm run lint:fix` -```sh +```bash # root project directory npm run lint # Find and fix linting errors automatically npm run lint:fix ``` - -Launch the prettier formatter. We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings](https://github.com/IQSS/vscode-settings) on GitHub. +Launch the prettier formatter. We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings]dv_repo_vscode_url on GitHub. -```sh +```bash # root project directory npm run format ```

    (back to top)

    - - - +
    +*** ### Running the project Locally @@ -388,70 +396,55 @@ This environment is intended for locally testing any functionality that requires There is an Nginx reverse proxy container on top of the frontend and backend containers to avoid CORS issues while testing the application. - **Run the environment** As the script argument, add the name of the Dataverse image tag you want to deploy. -```sh +```bash # /dev-env/ directory # Installs and runs project off latest tagged container image $ ./run-env.sh -# Removes ... +# Removes the project and its dependencies $ ./rm-env.sh ``` -Note that the image tag in the docker registry must to be pre pushed, otherwise the script will fail. You can find the existing tags on DockerHub [@gdcc/dataverse](https://hub.docker.com/r/gdcc/dataverse/tags) +Note that the image tag in the docker registry must to be pre pushed, otherwise the script will fail. You can find the existing tags on DockerHub [@gdcc/dataverse][dv_app_docker_image_url] If you are running the script for the first time, it may take a while, since npm has to install all project dependencies. This can also happen if you added new dependencies to `package.json`, or used the _uninstall_ script to remove current project files and shut down any running containers. Once the script has finished, you will be able to access Dataverse via: -- Dataverse SPA Frontend: [http://localhost:8000/spa](http://localhost:8000/spa) -- Dataverse JSF Application: [http://localhost:8000](http://localhost:8000) +- Dataverse SPA Frontend: [http://localhost:8000/spa][dv_app_localhost_spa_url] +- Dataverse JSF Application: [http://localhost:8000][dv_app_localhost_legacy_url] Note: The Dataverse configbaker takes some time to start the application, so the application will not be accessible until the bootstrapping is complete. **Adding custom test data** If you want to add test data (collections and datasets) to the Dataverse instance, run the following command: -```sh +```bash # /dev-env/ directory $ ./add-env-data.sh ``` -Note: The above command uses the [dataverse-sample-data](https://github.com/IQSS/dataverse-sample-data) repository whose scripts occasionally fail, so some of the test data may not be added. +Note: The above command uses the [dataverse-sample-data][dv_repo_dvsampledata_url] repository whose scripts occasionally fail, so some of the test data may not be added. - +*** ### Deployment -Once the site is built through the **`npm run build`** command, it can be deployed in different ways to different types of infrastructure, depending on installation needs. +Once the site is built through the `npm run build` command, it can be deployed in different ways to different types of infrastructure, depending the needs of the installation. We are working to provide different preconfigured automated deployment options, seeking to support common use cases today for installing applications of this nature. -The current automated deployment options are available within the GitHub **`deploy`** workflow, which is designed to be run manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment. +The current automated deployment options are available within the GitHub `deploy` workflow, which is designed to be run manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment. -#### Examples for AWS and Payara
    -AWS S3 Deployment [Expand] +Examples for AWS and Payara + +#### Deployment with AWS3 This option will build and deploy the application to a remote S3 bucket. @@ -488,10 +481,8 @@ Note that for the deployment to the S3 bucket to succeed, you must make the foll ``` You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; `http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` -
    -
    -Payara Deployment [Expand] +#### Deployment with Payara This option will build and deploy the application to a remote Payara server. @@ -509,14 +500,14 @@ A base path for the frontend application can be established on the remote server
    - - +
    +*** ## Usage Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. -_For more examples, please refer to the [Documentation](https://guides.dataverse.org/en/latest/developers/index.html)_ +_For more examples, please refer to the [Documentation][dv_docs_devs_url]_

    (back to top)

    @@ -524,6 +515,9 @@ _For more examples, please refer to the [Documentation](https://guides.dataverse +This project uses Atomic Design for it's Components. Here are several resources for Atomic Design if you are unfamiliar: + + @@ -532,6 +526,9 @@ _For more examples, please refer to the [Documentation](https://guides.dataverse +
    +*** + ## Roadmap - [ ] Add Changelog @@ -540,10 +537,14 @@ _For more examples, please refer to the [Documentation](https://guides.dataverse - [ ] More... -See the [open issues](https://github.com/IQSS/dataverse-frontend/issues) for a full list of proposed features (and known issues). +See the [open issues][dv_repo_issues_url] for a full list of proposed features (and known issues). +[Roadmap][hvd_iqss_roadmap_url], [Currently planned work][dv_repo_sprint_url]

    (back to top)

    +
    +*** + ## Contributing @@ -554,13 +555,18 @@ If you have a suggestion that would make this better, please fork the repo and c We love PRs! Read the Contributor Guidelines for more info. Say hello, share your tips/work, and spread the love on ... + +Got Questions? Join the conversation in FOO. +Find FOO videos and release overviews on our YouTube Channel, and check out the resources on our FOO org. +

    (back to top)

    - +
    +*** ## License @@ -568,13 +574,15 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform

    (back to top)

    - +
    +*** ## Contact Email us with software installation questions. Please note our response time is generally 24 business hours. + ### For developers and Dataverse Repositories @@ -590,234 +598,157 @@ Project Link: [https://github.com/IQSS/dataverse-frontend](https://github.com/IQ

    (back to top)

    + +
    +*** + ## Acknowledgments Chromatic -Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions. +Thanks to [Chromatic][_uses_chromatic_url] for providing the visual testing platform that helps us review UI changes and catch visual regressions.

    (back to top)

    + +*** + ### Built With This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples. - - - - - - - -

    (back to top)

    -
    - - -[![Node][Node.js]][Node-url] - -[Node.js]: https://img.shields.io/badge/node.js-000000?style=for-the-badge&logo=nodedotjs&logoColor=white -[Node-url]: https://nodejs.org/ - - - -[![React][React.js]][React-url] - -[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB -[React-url]: https://reactjs.org/ - - - -[![TypeScript][TypeScript]][Typescript-url] - -[TypeScript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white -[Typescript-url]: https://typescriptlang.org/ - -
    - - -[![Bootstrap][Bootstrap.com]][Bootstrap-url] - -[Bootstrap.com]: https://img.shields.io/badge/Bootstrap-563D7C?style=for-the-badge&logo=bootstrap&logoColor=white -[Bootstrap-url]: https://getbootstrap.com - - - -[![Cypress][Cypress.io]][Cypress-url] - -[Cypress.io]: https://img.shields.io/badge/Cypress-69D3A7?style=for-the-badge&logo=cypress&logoColor=black -[Cypress-url]: https://cypress.io/ - - - -[![TestingLibrary][TestingLibrary]][TestingLibrary-url] - -[TestingLibrary]: https://img.shields.io/badge/TestingLibrary-E33332?style=for-the-badge&logo=testinglibrary&logoColor=white -[TestingLibrary-url]: https://svelte.dev/ - - - -[![Storybook][Storybook.com]][Storybook-url] - -[Storybook.com]: https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white -[Storybook-url]: https://laravel.com - - - -[![GH-Contributors][GH-Contributors-shield]][GH-Contributors-url] - -[GH-Contributors-shield]: https://img.shields.io/github/contributors/IQSS/dataverse-frontend?branch=develop&style=for-the-badge -[GH-Contributors-url]: https://github.com/IQSS/dataverse-frontend/graphs/contributors - - - -[![Coveralls Coverage][Coveralls-badge]][Coveralls-url] - -[Coveralls-badge]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge&logo=coveralls -[Coveralls-url]: https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop - - - -[![WorkflowStatus][Workflow-badge]][Workflow-url] - -[Workflow-badge]: https://img.shields.io/github/actions/workflow/status/IQSS/dataverse-frontend/test.yml?branch=develop&style=for-the-badge -[Workflow-url]: https://github.com/IQSS/dataverse-frontend/actions - - - -![GitHub forks](https://img.shields.io/github/forks/IQSS/dataverse-frontend?style=for-the-badge) - - - -![GitHub Tag](https://img.shields.io/github/v/tag/iqss/dataverse-frontend?style=for-the-badge) - - - -[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.][RepoStatus-badge]][RepoStatus-url] - -[RepoStatus-badge]: https://img.shields.io/badge/repo_status-WIP-yellow?style=for-the-badge -[RepoStatus-url]: https://www.repostatus.org/#wip - -[![TestsStatus][TestsStatus-badge]][TestsStatus-url] - -[TestsStatus-badge]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml/badge.svg -[TestsStatus-url]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml - - - - -[![Stargazers][stars-badge]][stars-url] - -[stars-badge]: https://img.shields.io/github/stars/iqss/dataverse-frontend?style=for-the-badge -[stars-url]: https://github.com/IQSS/dataverse-frontend/stargazers - - - -[![Open issues][issue-badge]][issue-url] - -[issue-badge]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge -[issue-url]: https://github.com/IQSS/dataverse-frontend/issues - - - -[DockerDesktop-badge]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white -[DockerDesktop-url]: https://www.docker.com/products/docker-desktop/ - - -[AmazonS3-badge]: https://img.shields.io/badge/AmazonS3-569A31?style=for-the-badge&logo=amazons3&logoColor=white -[AmazonS3-url]: https://aws.amazon.com/ - -[Payara-url]: https://www.payara.fish/ - - - -[product-screenshot]: images/screenshot.png - -[forks-shield]: https://img.shields.io/github/forks/othneildrew/Best-README-Template.svg?style=for-the-badge -[forks-url]: https://github.com/othneildrew/Best-README-Template/network/members -[stars-shield]: https://img.shields.io/github/stars/othneildrew/Best-README-Template.svg?style=for-the-badge -[stars-url]: https://github.com/othneildrew/Best-README-Template/stargazers -[license-shield]: https://img.shields.io/github/license/othneildrew/Best-README-Template.svg?style=for-the-badge -[license-url]: https://github.com/othneildrew/Best-README-Template/blob/master/LICENSE.txt -[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 -[linkedin-url]: https://linkedin.com/in/othneildrew -[JQuery.com]: https://img.shields.io/badge/jQuery-0769AD?style=for-the-badge&logo=jquery&logoColor=white -[JQuery-url]: https://jquery.com - - - -[npm-url]: https://www.npmjs.com/package/react-parallax-tilt -[npm-badge]: https://img.shields.io/npm/v/react-parallax-tilt.svg -[size-url]: https://bundlephobia.com/package/react-parallax-tilt -[size-badge]: https://badgen.net/bundlephobia/minzip/react-parallax-tilt -[downloads-badge]: https://img.shields.io/npm/dm/react-parallax-tilt.svg?color=blue -[lint-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/lint.yml/badge.svg -[lint-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/lint.yml -[tsc-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/tsc.yml/badge.svg -[tsc-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/tsc.yml -[build-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/build.yml/badge.svg -[build-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/build.yml -[test-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/test.yml/badge.svg -[test-url]: https://react-parallax-tilt-test-unit-report.netlify.app/ -[test-e2e-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/test-e2e.yml/badge.svg -[test-e2e-url]: https://react-parallax-tilt-test-e2e-report.netlify.app/ -[deploy-storybook-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/deploy-storybook.yml/badge.svg -[deploy-storybook-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/deploy-storybook.yml -[npm-release-badge]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/npm-release.yml/badge.svg -[npm-release-url]: https://github.com/mkosir/react-parallax-tilt/actions/workflows/npm-release.yml -[semantic-badge]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg -[semantic-url]: https://github.com/semantic-release/semantic-release - - + + + - + +[dv_repo_url]: https://github.com/IQSS/dataverse-frontend +[dv_repo_issues_url]: https://github.com/IQSS/dataverse-frontend/issues +[dv_repo_sprint_url]: https://github.com/orgs/IQSS/projects/34/views/23 +[dv_repo_contributors_url]: https://github.com/IQSS/dataverse-frontend/graphs/contributors +[dv_repo_stargazers_url]: https://github.com/IQSS/dataverse-frontend/stargazers +[dv_repo_coveralls_url]: https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop +[dv_repo_workflow_url]: https://github.com/IQSS/dataverse-frontend/actions +[dv_repo_forks_url]: https://github.com/IQSS/dataverse-frontend/forks +[dv_repo_tag_url]: https://github.com/IQSS/dataverse-frontend/tags +[dv_repo_projectstatus_url]: https://www.repostatus.org/#wip +[dv_repo_teststatus_url]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml +[dv_repo_releases_url]: https://github.com/IQSS/dataverse-frontend/releases + + + +[dv_repo_dvclientjs_url]: https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript +[dv_repo_dvclientjs_npm_url]: https://www.npmjs.com/package/js-dataverse +[dv_repo_dvsampledata_url]: https://github.com/IQSS/dataverse-sample-data +[dv_repo_legacyjsf_url]: https://github.com/IQSS/dataverse/ +[dv_repo_legacyjsf_releases_url]: https://github.com/IQSS/dataverse/releases +[dv_repo_legacyjsf_issues_url]: https://github.com/IQSS/dataverse/issues +[dv_repo_vscode_url]: https://github.com/IQSS/vscode-settings + + + +[dv_app_beta_spa_url]: https://beta.dataverse.org/spa +[dv_app_beta_legacyjsf_url]: https://beta.dataverse.org +[dv_app_legacyjsf_demo_url]: https://demo.dataverse.org/ +[dv_app_localhost_build_url]: http://localhost:5173 +[dv_app_localhost_storybook_url]: http://localhost:6006/ +[dv_app_localhost_designsystem_url]: http://localhost:6007/ +[dv_app_localhost_spa_url]: http://localhost:8000/spa +[dv_app_localhost_legacy_url]: http://localhost:8000/ + +[dv_app_docker_image_url]: https://hub.docker.com/r/gdcc/dataverse/tags + + + +[dv_community_gdcc_url]: https://www.gdcc.io/ +[dv_community_gdcc_ui_url]: https://ui.gdcc.io/ +[dv_community_gdcc_containers_url]: https://ct.gdcc.io/ +[dv_community_google_devs_url]: https://groups.google.com/g/dataverse-dev +[dv_community_google_users_url]: https://groups.google.com/g/dataverse-community +[dv_community_zulip_url]: https://dataverse.zulipchat.com/ + + + +[hvd_iqss_url]: https://www.iq.harvard.edu/ +[hvd_iqss_roadmap_url]: https://www.iq.harvard.edu/roadmap-dataverse-project +[hvd_legacyjsf_url]: https://dataverse.harvard.edu/ + + + +[dv_docs_dataverse_url]: https://dataverse.org/ +[dv_docs_about_url]: https://dataverse.org/about +[dv_docs_styleguide_url]: https://guides.dataverse.org/en/latest/style/index.html +[dv_docs_api_url]: http://guides.dataverse.org/en/latest/api/index.html +[dv_docs_devs_url]: https://guides.dataverse.org/en/latest/developers/index.html +[dv_docs_github_userauthtoken_url]: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app +[dv_docs_github_token_url]: https://github.com/settings/tokens + + + +[_uses_reactjs_url]: https://reactjs.org/ +[_uses_nodejs_url]: https://nodejs.org/ +[_uses_typescript_url]: https://typescriptlang.org/ +[_uses_bootstrap_url]: https://getbootstrap.com +[_uses_cypress_url]: https://cypress.io/ +[_uses_testinglibrary_url]: https://testing-library.com/docs/react-testing-library/intro/ +[_uses_storybook_url]: https://storybook.js.org/ +[_uses_payara_url]: https://www.payara.fish/ +[_uses_docker_url]: https://www.docker.com/products/docker-desktop/ +[_uses_aws3_url]: https://aws.amazon.com/ +[_uses_chromatic_url]: https://www.chromatic.com/ + +[_uses_repo_cra_error_url]: https://github.com/facebook/create-react-app/issues/11174 +[_uses_tool_chromatic_url]: https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd + +[_uses_lib_grep_url]: https://www.npmjs.com/package/@cypress/grep + + + + +[_shield_reactjs]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB +[_shield_nodejs]: https://img.shields.io/badge/node.js-000000?style=for-the-badge&logo=nodedotjs&logoColor=white +[_shield_typescript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white +[_shield_bootstrap]: https://img.shields.io/badge/Bootstrap-563D7C?style=for-the-badge&logo=bootstrap&logoColor=white +[_shield_cypress]: https://img.shields.io/badge/Cypress-69D3A7?style=for-the-badge&logo=cypress&logoColor=black +[_shield_testinglibrary]: https://img.shields.io/badge/TestingLibrary-E33332?style=for-the-badge&logo=testinglibrary&logoColor=white +[_shield_storybook]: https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white +[_shield_docker]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white +[_shield_amazons3]: https://img.shields.io/badge/AmazonS3-569A31?style=for-the-badge&logo=amazons3&logoColor=white + +[_shield_projectstatus]: https://img.shields.io/badge/repo_status-WIP-yellow?style=for-the-badge +[_shield_contributors]: https://img.shields.io/github/contributors/IQSS/dataverse-frontend?branch=develop&style=for-the-badge +[_shield_teststatus]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml/badge.svg +[_shield_stargazers]: https://img.shields.io/github/stars/iqss/dataverse-frontend?style=for-the-badge +[_shield_coveralls]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge&logo=coveralls + +[_shield_workflow]: https://img.shields.io/github/actions/workflow/status/IQSS/dataverse-frontend/test.yml?branch=develop&style=for-the-badge +[_shield_issues]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge +[_shield_forks]: https://img.shields.io/github/forks/IQSS/dataverse-frontend?style=for-the-badge +[_shield_tag]: https://img.shields.io/github/v/tag/iqss/dataverse-frontend?style=for-the-badge + + + +[_img_dv_logo_withbackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6986476f-39ba-46a4-9be0-f05cd8e92244 +[_img_dv_logo_nobackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6c4d79e4-7be5-4102-88bd-dfa167dc79d3 +[_img_screenshot]: images/screenshot.png + + + +[_video_demo_datasetpage_url]: https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ + +[_video_demo_filetable_url]: https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ + + + +[_social_twitter]: https://twitter.com/your_username + - - - - - - - - - - - - - - - - - - - - - - - - -*** \ No newline at end of file From 970bb84d9081da80169f42cd906a79284f4a77a8 Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Tue, 5 Mar 2024 11:26:20 -0500 Subject: [PATCH 06/26] formatting, removing second logo --- README.md | 73 ++++++++++++++++++------------------------------------- 1 file changed, 23 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 856004c9f..c04c14a94 100644 --- a/README.md +++ b/README.md @@ -11,23 +11,12 @@ *** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use. *** https://www.markdownguide.org/basic-syntax/#reference-style-links --> - - - -
    Logo - Logo

    Dataverse Frontend

    @@ -41,11 +30,11 @@ Report Bug | Request Feature

    -
    +

    Progress Demo Videos

    - Dataset Overview Page (Aug. '23) | - Dataset Files Table (Dec. '23) + Dataset Overview Page (Aug. '23) | + Dataset Files Table (Dec. '23)

    @@ -107,14 +96,12 @@ For more information and a list of additional resources, please visit this [disc The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [Dataverse Website][dv_docs_dataverse_url] -
    -### What is Dataverse Frontend _& How do they differ?_ +### What is Dataverse Frontend _& How is it different?_ The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations and utilize the JavaScript framework of their choice. -
    **The goals of Dataverse Frontend:** @@ -137,7 +124,6 @@ The Dataverse Frontend repository is an initiative undertaken in 2023 to moderni - Cypress testing automation - Storybook for UI Component Library -
    *** ### Beta Testing Environment @@ -164,18 +150,18 @@ The environment is accessible through the following URLs:
    - Changes from the original Dataverse JSF application + Changes from the original Dataverse JSF application - >##### Changes from the Style Guide + >### Changes from the Style Guide > >The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. > - >###### Links + >#### Links > >We added an underline to links to make them accessible. > - >###### File label + >#### File label > >Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies the secondary color to the labels automatically, the color of the file label is now the global secondary color which is @@ -183,11 +169,11 @@ The environment is accessible through the following URLs: > >We changed the citation block to be white with a colored border, to make the text in the box more accessible. > - >##### Changes in functionality behavior + >### Changes in functionality behavior > >Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. > - >###### Dataset files tab search + >#### Dataset files tab search > >The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. > @@ -199,25 +185,25 @@ The environment is accessible through the following URLs:

    (back to top)

    -
    -*** ## Getting Started _To get a local copy up and running follow these simple example steps._ ### Prerequisites -[![DockerDesktop][_shield_docker]][_uses_docker_url-url] + +[![DockerDesktop][_shield_docker]][_uses_docker_url] 1. **Node & NPM**: `node >= v16` and `npm >= v8`. Recommended versions for this project are `node v19` and `npm v9`. -2. **Docker**: We use Docker Desktop, but the Docker CLI will also work! -3. **Create and add your NPM and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps outlined below: -4. Navigate to the project directory root and duplicate `.npmrc.example`, saving the copy as `.npmrc`. +2. **Docker**: We use Docker Desktop, but the Docker CLI will also work. +3. **Create a copy of .npmrc**: In the project directory root, duplicate `.npmrc.example`, saving the copy as `.npmrc`. + > ```bash > # root project directory > cp .npmrc.example .npmrc > ``` -5. Follow the steps outlined below to generate a personal access token used to interface with the GitHub API. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url] + +4. **Create and add your NPM and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps outlined below. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url]. > **Getting a GitHub token** > 1. Go to your GitHub [Personal Access Tokens][dv_docs_github_token_url] settings @@ -226,7 +212,9 @@ _To get a local copy up and running follow these simple example steps._ > 4. Copy the generated token and replace the string `YOUR_GITHUB_AUTH_TOKEN` in the previously created `.npmrc` file. > Now, you should be able to install the [Dataverse JavaScript][dv_repo_dvclientjs_url] client using npm. -```.npmrc +Your .npmrc file should resemble the following: + +```properties # .npmrc legacy-peer-deps=true @@ -238,8 +226,6 @@ legacy-peer-deps=true ### Installation & Setup -_Below is an example of how you can instruct your audience on installing and setting up your app. This template doesn't rely on any external dependencies or services._ - 1. Install the project & its dependencies ```bash @@ -302,14 +288,8 @@ npm run build-storybook Note that both Storybook instances are also published to Chromatic as part of the build and merge processes, located at: -[![DataverseFrontend][DataverseFrontend-Chromatic]][DataverseFrontend-Chromatic-url] - - - -[![DataverseDesignSystem][DataverseDesignSystem-Chromatic]][DataverseDesignSystem-Chromatic-url] - - - +- [DataverseFrontend-Chromatic](https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd) +- [DataverseDesignSystem-Chromatic](https://www.chromatic.com/builds?appId=646fbe232a8d3b501a1943f3) **Testing with Cypress:** @@ -373,7 +353,7 @@ npm run lint npm run lint:fix ``` -Launch the prettier formatter. We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings]dv_repo_vscode_url on GitHub. +Launch the prettier formatter. We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings][dv_repo_vscode_url] on GitHub. ```bash @@ -500,8 +480,6 @@ A base path for the frontend application can be established on the remote server
    -
    -*** ## Usage @@ -526,9 +504,6 @@ This project uses Atomic Design for it's Components. Here are several resources -
    -*** - ## Roadmap - [ ] Add Changelog @@ -542,8 +517,6 @@ See the [open issues][dv_repo_issues_url] for a full list of proposed features (

    (back to top)

    -
    -*** From d1c99b1589c8fe54770faf5da550a39177d67735 Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Tue, 5 Mar 2024 11:42:53 -0500 Subject: [PATCH 07/26] formatting --- README.md | 111 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 58 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index c04c14a94..8fcffb438 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ For more information and a list of additional resources, please visit this [disc ### What is Dataverse? -The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [Dataverse Website][dv_docs_dataverse_url] +The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [Dataverse Website][dv_docs_dataverse_url]. @@ -148,7 +148,6 @@ The environment is accessible through the following URLs: - The SPA will continue its life as a separate application, supported on its own maintenance schedule. - When the SPA has matured enough for an official release, we will switch to the new version and the old backend (Link to repository) will be moved into maintenance mode with no new features being introduced and focusing only on critical bugfixes. -
    Changes from the original Dataverse JSF application @@ -245,8 +244,7 @@ npm install cd packages/design-system && npm run build ``` -### Additional scrips available - +*** **Running & building the app:** @@ -263,6 +261,7 @@ The application will actively watch the directory for changes and reload when ch ```bash # Build the app for production to the `/dist/` directory: npm run build + # Locally preview the production build: npm run preview @@ -297,74 +296,86 @@ Use the following commands to ensure your build passes checks for coding standar ```bash # root project directory + # Launches the Cypress test runner for the end-to-end [or unit] tests: npm run test:e2e [test:unit] + # If you prefer to see the tests executing in Cypress you can run: npm run cy:open-e2e [cy:open-unit] + # See current code coverage npm run test:coverage ``` -**Using `grep` with Cypress** - -The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. - -Some examples used by the grep library are below for reference: - -```bash -# root project directory +
    +Using `grep` with Cypress -# run only the tests with "auth user" in the title -$ npx cypress run --env grep="auth user" -# run tests with "hello" or "auth user" in their titles -# by separating them with ";" character -$ npx cypress run --env grep="hello; auth user" -``` +>The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. +> +>Some examples used by the grep library are below for reference: +> +>```bash +># root project directory +> +># run only the tests with "auth user" in the title +>$ npx cypress run --env grep="auth user" +> +># run tests with "hello" or "auth user" in their titles by separating them with ";" character +>$ npx cypress run --env grep="hello; auth user" +>``` +> +>To target specific tests, add `--spec` argument +> +>```bash +># root project directory +> +>$ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" +>\ --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +>``` +> +> +>**Repeat and burn tests** +>You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in the spec A five times using: +> +>```bash +># root project directory +> +>$ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +>``` +> -To target specific tests, add `--spec` argument +
    -```bash -# root project directory -$ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" -\ --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx -``` +**Formatting and Linting:** +Launch the linter. -**Repeat and burn tests** -You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in the spec A five times using: +To attempt to automatically fix any errors found, use `npm run lint:fix` ```bash # root project directory -$ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx -``` - -**Formatting and Linting:** - -Launch the linter. To attempt to automatically fix any errors found, use `npm run lint:fix` - -```bash -# root project directory npm run lint + # Find and fix linting errors automatically npm run lint:fix ``` -Launch the prettier formatter. We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings][dv_repo_vscode_url] on GitHub. +Launch the prettier formatter. + +We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings][dv_repo_vscode_url] on GitHub. ```bash # root project directory + npm run format ``` -

    (back to top)

    -
    -*** ### Running the project Locally @@ -405,13 +416,12 @@ If you want to add test data (collections and datasets) to the Dataverse instanc ```bash # /dev-env/ directory + $ ./add-env-data.sh ``` Note: The above command uses the [dataverse-sample-data][dv_repo_dvsampledata_url] repository whose scripts occasionally fail, so some of the test data may not be added. -*** - ### Deployment Once the site is built through the `npm run build` command, it can be deployed in different ways to different types of infrastructure, depending the needs of the installation. @@ -480,6 +490,9 @@ A base path for the frontend application can be established on the remote server
    +

    (back to top)

    +
    + ## Usage @@ -533,22 +546,18 @@ Got Questions? Join the conversation in FOO. Find FOO videos and release overviews on our YouTube Channel, and check out the resources on our FOO org.

    (back to top)

    +
    - -
    -*** - ## License Distributed under the Apache License, Version 2.0. See `LICENSE` for more information.

    (back to top)

    +
    -
    -*** ## Contact @@ -572,8 +581,6 @@ Project Link: [https://github.com/IQSS/dataverse-frontend](https://github.com/IQ

    (back to top)

    -
    -*** @@ -584,7 +591,7 @@ Project Link: [https://github.com/IQSS/dataverse-frontend](https://github.com/IQ Thanks to [Chromatic][_uses_chromatic_url] for providing the visual testing platform that helps us review UI changes and catch visual regressions.

    (back to top)

    - +
    *** @@ -593,14 +600,12 @@ Thanks to [Chromatic][_uses_chromatic_url] for providing the visual testing plat This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples.

    (back to top)

    - +
    - - From ae5db429d38266bdb12a6bce374388bc39a23d66 Mon Sep 17 00:00:00 2001 From: Matt Mangan Date: Tue, 5 Mar 2024 14:10:01 -0500 Subject: [PATCH 08/26] adding logos, fixing links --- README.md | 166 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 93 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 8fcffb438..bec0b8830 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,14 @@ +[![CI][_shield_projectstatus]][dv_repo_projectstatus_url] +[![CI][_shield_contributors]][dv_repo_contributors_url] +[![CI][_shield_stargazers]][dv_repo_stargazers_url] +[![CI][_shield_coveralls]][dv_repo_coveralls_url] +[![CI][_shield_workflow]][dv_repo_workflow_url] +[![CI][_shield_issues]][dv_repo_issues_url] +[![CI][_shield_forks]][dv_repo_forks_url] + For more information and a list of additional resources, please visit this [discussion](#). --- @@ -56,7 +70,7 @@ For more information and a list of additional resources, please visit this [disc @@ -68,14 +82,10 @@ For more information and a list of additional resources, please visit this [disc
  • Running the Project Locally
    • -
  • Deployment - -
    • -
  • Usage
    • -
  • Components
    • -
  • Code
    • +
  • Deployment
    • + + +
  • Roadmap
  • Contributing
  • License
    • @@ -86,7 +96,7 @@ For more information and a list of additional resources, please visit this [disc -## About The Project +## About the Project [![Product Name Screen Shot][_img_screenshot]][_img_screenshot] @@ -142,7 +152,7 @@ The environment is accessible through the following URLs: - Dataverse JSF: [beta.dataverse.org][dv_app_beta_legacyjsf_url] -### How existing Dataverse installations may be affected +### How Existing Dataverse Installations May Be Affected - The existing Dataverse API will be added to and extended from the present backend architecture while the existing UI and current Dataverse functionalities are preserved. - The SPA will continue its life as a separate application, supported on its own maintenance schedule. @@ -152,7 +162,7 @@ The environment is accessible through the following URLs: Changes from the original Dataverse JSF application - >### Changes from the Style Guide + >### Changes From the Style Guide > >The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. > @@ -160,7 +170,7 @@ The environment is accessible through the following URLs: > >We added an underline to links to make them accessible. > - >#### File label + >#### File Labels > >Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies the secondary color to the labels automatically, the color of the file label is now the global secondary color which is @@ -168,11 +178,11 @@ The environment is accessible through the following URLs: > >We changed the citation block to be white with a colored border, to make the text in the box more accessible. > - >### Changes in functionality behavior + >### Changes in Functionality & Behavior > >Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. > - >#### Dataset files tab search + >#### Dataset Files Tab Search > >The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. > @@ -195,25 +205,26 @@ _To get a local copy up and running follow these simple example steps._ 1. **Node & NPM**: `node >= v16` and `npm >= v8`. Recommended versions for this project are `node v19` and `npm v9`. 2. **Docker**: We use Docker Desktop, but the Docker CLI will also work. -3. **Create a copy of .npmrc**: In the project directory root, duplicate `.npmrc.example`, saving the copy as `.npmrc`. +3. **Create a Copy of .npmrc**: In the project directory root, duplicate `.npmrc.example`, saving the copy as `.npmrc`. > ```bash > # root project directory > cp .npmrc.example .npmrc > ``` -4. **Create and add your NPM and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps outlined below. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url]. +4. **Create and Add Your Npm and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps outlined below. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url]. - > **Getting a GitHub token** + > **Getting a GitHub Token** > 1. Go to your GitHub [Personal Access Tokens][dv_docs_github_token_url] settings > 2. Select `Generate new token (classic)` > 3. Give the token a name and select scope `read:packages` > 4. Copy the generated token and replace the string `YOUR_GITHUB_AUTH_TOKEN` in the previously created `.npmrc` file. > Now, you should be able to install the [Dataverse JavaScript][dv_repo_dvclientjs_url] client using npm. -Your .npmrc file should resemble the following: +Afterwards, your .npmrc file should resemble the following: ```properties + # .npmrc legacy-peer-deps=true @@ -229,6 +240,7 @@ legacy-peer-deps=true ```bash # root project directory + npm install ``` > [!WARNING] @@ -244,14 +256,15 @@ npm install cd packages/design-system && npm run build ``` -*** -**Running & building the app:** + +**Running & Building the App:** Run the app in the development mode. Open [http://localhost:5173][dv_app_localhost_build_url] to view it in your browser. ```bash # root project directory + npm start ``` @@ -259,6 +272,8 @@ The application will actively watch the directory for changes and reload when ch ```bash +# root project directory + # Build the app for production to the `/dist/` directory: npm run build @@ -266,6 +281,7 @@ npm run build npm run preview ``` +
    **Storybook:** @@ -277,8 +293,9 @@ There are 2 Storybook instances, one for the general Design System and one for t ```bash # $ cd packages/design-system -npm run storybook + # `npm run storybook` should automatically open in your default browser +npm run storybook # $ cd packages/design-system npm run build-storybook @@ -286,10 +303,11 @@ npm run build-storybook ``` Note that both Storybook instances are also published to Chromatic as part of the build and merge processes, located at: - - [DataverseFrontend-Chromatic](https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd) - [DataverseDesignSystem-Chromatic](https://www.chromatic.com/builds?appId=646fbe232a8d3b501a1943f3) +
    + **Testing with Cypress:** Use the following commands to ensure your build passes checks for coding standards and coverage: @@ -307,7 +325,7 @@ npm run cy:open-e2e [cy:open-unit] npm run test:coverage ``` - +
    Using `grep` with Cypress @@ -348,6 +366,7 @@ npm run test:coverage
    +
    **Formatting and Linting:** @@ -377,7 +396,7 @@ npm run format
    -### Running the project Locally +### Running the Project Locally A containerized environment, oriented to local development, is available to be run from the repository. @@ -387,8 +406,10 @@ This environment is intended for locally testing any functionality that requires There is an Nginx reverse proxy container on top of the frontend and backend containers to avoid CORS issues while testing the application. +
    + +**Run the Environment** -**Run the environment** As the script argument, add the name of the Dataverse image tag you want to deploy. ```bash @@ -405,13 +426,15 @@ Note that the image tag in the docker registry must to be pre pushed, otherwise If you are running the script for the first time, it may take a while, since npm has to install all project dependencies. This can also happen if you added new dependencies to `package.json`, or used the _uninstall_ script to remove current project files and shut down any running containers. Once the script has finished, you will be able to access Dataverse via: - - Dataverse SPA Frontend: [http://localhost:8000/spa][dv_app_localhost_spa_url] - Dataverse JSF Application: [http://localhost:8000][dv_app_localhost_legacy_url] Note: The Dataverse configbaker takes some time to start the application, so the application will not be accessible until the bootstrapping is complete. -**Adding custom test data** +
    + +**Adding Custom Test Data** + If you want to add test data (collections and datasets) to the Dataverse instance, run the following command: ```bash @@ -421,6 +444,7 @@ $ ./add-env-data.sh ``` Note: The above command uses the [dataverse-sample-data][dv_repo_dvsampledata_url] repository whose scripts occasionally fail, so some of the test data may not be added. +
    ### Deployment @@ -447,9 +471,9 @@ For this workflow to work, a GitHub environment must be configured with the foll Note that for the deployment to the S3 bucket to succeed, you must make the following changes to the bucket via the S3 web interface (or equivalent changes using aws-cli or similar tools): - - Under "_Permissions_", "_Permissions overview_", "_Block public access (bucket settings)_", click "_Edit_", then __uncheck__ "_Block all public access_" and save. - - Under "Properties", "Static website hosting", click "Edit" and enable it. Change "Index document" and "Error document" to "index.html". - - Under "Bucket policy", click "Edit" and paste the following policy (changing `` to your bucket name) and save. + - Under _`Permissions`_ ⏵ _`Permissions Overview`_ ⏵ _`Block public access (bucket settings)`_ ⏵ click _`Edit`_, then __uncheck__ _`Block all public access`_ and save. + - Under _`Properties`_ ⏵ _`Static website hosting`_ ⏵ click _`Edit`_ and enable it. Change _`Index document`_ and _`Error document`_ to `index.html`. + - Under _`Bucket Policy`_, click _`Edit`_ and paste the following policy (changing `` to your bucket name) and save. ```json { @@ -500,50 +524,47 @@ Use this space to show useful examples of how a project can be used. Additional _For more examples, please refer to the [Documentation][dv_docs_devs_url]_ -

    (back to top)

    - - + This project uses Atomic Design for it's Components. Here are several resources for Atomic Design if you are unfamiliar: - - - + - +

    (back to top)

    +
    ## Roadmap -- [ ] Add Changelog -- [ ] Add Additional Templates w/ Examples -- [ ] Add "Components" document to easily copy & paste sections of the readme -- [ ] More... +Interested in what's being developed currently? See the [open issues][dv_repo_issues_url] for a full list of proposed features (and known issues), and what we are working on in the [currently planned sprint][dv_repo_sprint_url]. +Keep an eye out on [The Institute for Quantitative Social Science (IQSS) Dataverse Roadmap][hvd_iqss_roadmap_url] at Harvard University to get a look at upcoming initiatives for the project. -See the [open issues][dv_repo_issues_url] for a full list of proposed features (and known issues). -[Roadmap][hvd_iqss_roadmap_url], [Currently planned work][dv_repo_sprint_url] + +

    (back to top)

    - +
    ## Contributing -Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. +We love PRs! Read the Contributor Guidelines for more info. Any contributions you make are **greatly appreciated**. -If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "`enhancement`". +If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the `enhancement` tag. -We love PRs! Read the Contributor Guidelines for more info. Say hello, share your tips/work, and spread the love on ... +Got Questions? Join the conversation on [Zulip][dv_community_zulip_url], or our Google Groups for [Developers][dv_community_google_devs_url] and [Users][dv_community_google_users_url]. Or attend community meetings, hosted by the The Global Dataverse Community Consortium to collaborate with the interest groups for [Frontend Development][dv_community_gdcc_ui_url] and [Containerization][dv_community_gdcc_containers_url], learn and share with communities around the world! - -Got Questions? Join the conversation in FOO. -Find FOO videos and release overviews on our YouTube Channel, and check out the resources on our FOO org. + +Find videos and release overviews on our YouTube Channel, and check out the resources on our [website][dv_docs_dataverse_url].

    (back to top)


    @@ -551,13 +572,6 @@ Find FOO videos and release overviews on our YouTube Channel, and check out the -## License - -Distributed under the Apache License, Version 2.0. See `LICENSE` for more information. - -

    (back to top)

    -
    - ## Contact @@ -566,24 +580,20 @@ Email us with software installation questions. Please note our response time is -### For developers and Dataverse Repositories +### For Developers and Dataverse Repositories -Report issues and contribute to our code: Report bugs and add feature requests in GitHub Issues or use GitHub pull requests, if you have some code, scripts or documentation that you'd like to share. If you have a security issue to report, please email security@dataverse.org. +**Report issues and contribute to our code**: -Ask a question or start a discussion: A great place to publicly share feedback, ideas, feature requests, and troubleshoot any issues is in the dataverse-community mailing list. Additional mailing lists are available, including language-specific ones. +Report bugs and add feature requests in GitHub Issues or use GitHub pull requests, if you have some code, scripts or documentation that you'd like to share. If you have a security issue to report, please email security@dataverse.org. -Chat with us at chat.dataverse.org. +Ask a question or start a discussion: A great place to publicly share feedback, ideas, feature requests, and troubleshoot any issues is in the dataverse-community mailing list. Additional mailing lists are available, including language-specific ones. -Your Name - [@your_twitter](https://twitter.com/your_username) - email@example.com -Project Link: [https://github.com/IQSS/dataverse-frontend](https://github.com/IQSS/dataverse-frontend)

    (back to top)

    +
    - - - ## Acknowledgments Chromatic @@ -602,6 +612,16 @@ This section should list any major frameworks/libraries used to bootstrap your p

    (back to top)


    +*** + +## License + +Distributed under the Apache License, Version 2.0. See `LICENSE` for more information. + +

    (back to top)

    +
    + + @@ -619,7 +639,6 @@ This section should list any major frameworks/libraries used to bootstrap your p [dv_repo_forks_url]: https://github.com/IQSS/dataverse-frontend/forks [dv_repo_tag_url]: https://github.com/IQSS/dataverse-frontend/tags [dv_repo_projectstatus_url]: https://www.repostatus.org/#wip -[dv_repo_teststatus_url]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml [dv_repo_releases_url]: https://github.com/IQSS/dataverse-frontend/releases @@ -683,7 +702,6 @@ This section should list any major frameworks/libraries used to bootstrap your p [_uses_docker_url]: https://www.docker.com/products/docker-desktop/ [_uses_aws3_url]: https://aws.amazon.com/ [_uses_chromatic_url]: https://www.chromatic.com/ - [_uses_repo_cra_error_url]: https://github.com/facebook/create-react-app/issues/11174 [_uses_tool_chromatic_url]: https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd @@ -701,12 +719,14 @@ This section should list any major frameworks/libraries used to bootstrap your p [_shield_storybook]: https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white [_shield_docker]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white [_shield_amazons3]: https://img.shields.io/badge/AmazonS3-569A31?style=for-the-badge&logo=amazons3&logoColor=white +[_shield_zulip]: https://img.shields.io/badge/zulip-chat?style=for-the-badge&logo=zulip&logoColor=%236492FE +[_shield_googledevs]: https://img.shields.io/badge/Developer_Group-white?style=for-the-badge&logo=google +[_shield_googleusers]: https://img.shields.io/badge/User_Group-white?style=for-the-badge&logo=google [_shield_projectstatus]: https://img.shields.io/badge/repo_status-WIP-yellow?style=for-the-badge [_shield_contributors]: https://img.shields.io/github/contributors/IQSS/dataverse-frontend?branch=develop&style=for-the-badge -[_shield_teststatus]: https://github.com/IQSS/dataverse-frontend/actions/workflows/test.yml/badge.svg [_shield_stargazers]: https://img.shields.io/github/stars/iqss/dataverse-frontend?style=for-the-badge -[_shield_coveralls]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge&logo=coveralls +[_shield_coveralls]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge [_shield_workflow]: https://img.shields.io/github/actions/workflow/status/IQSS/dataverse-frontend/test.yml?branch=develop&style=for-the-badge [_shield_issues]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge From 7731842774f9e87b06222acf1f888cd7f3f87958 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 18 Mar 2024 18:56:42 +0100 Subject: [PATCH 09/26] feat(Developer Guide): add Writting test cases section --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/SUPPORT.md | 1 - .storybook/main.ts | 14 +- CONTRIBUTING.md | 1 + README.md | 477 ++++++++++++++++++++++++------- 5 files changed, 377 insertions(+), 118 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fbfad5f96..f28b0de8c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,4 +12,4 @@ ## Is there a release notes update needed for this change?: -## Additional documentation: \ No newline at end of file +## Additional documentation: diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index 8d74d941f..73b3c774d 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -1,4 +1,3 @@ - # Looking for support? We want to help Please post your question to X (#) using the Timber tag. diff --git a/.storybook/main.ts b/.storybook/main.ts index f7066d01f..e0c6acb07 100644 --- a/.storybook/main.ts +++ b/.storybook/main.ts @@ -1,16 +1,16 @@ -import { dirname, join } from "path"; +import { dirname, join } from 'path' import type { StorybookConfig } from '@storybook/react-vite' const config: StorybookConfig = { stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'], addons: [ - getAbsolutePath("@storybook/addon-links"), - getAbsolutePath("@storybook/addon-essentials"), - getAbsolutePath("@storybook/addon-interactions"), - getAbsolutePath("@storybook/addon-a11y") + getAbsolutePath('@storybook/addon-links'), + getAbsolutePath('@storybook/addon-essentials'), + getAbsolutePath('@storybook/addon-interactions'), + getAbsolutePath('@storybook/addon-a11y') ], framework: { - name: getAbsolutePath("@storybook/react-vite"), + name: getAbsolutePath('@storybook/react-vite'), options: {} }, docs: { @@ -21,5 +21,5 @@ const config: StorybookConfig = { export default config function getAbsolutePath(value: string): any { - return dirname(require.resolve(join(value, "package.json"))); + return dirname(require.resolve(join(value, 'package.json'))) } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43f6b1790..8b967beb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -132,6 +132,7 @@ We use a [CODEOWNERS](https://github.com/iqss/dataverse-frontend/blob/master/.gi By contributing code you are granting _(`Dataverse`)_ shared ownership of your work. You still own it but _(`Dataverse`)_ will have the right to relicense your work based on our needs & treat this work as if it was developed by a _(`Dataverse`)_ engineer. ## Browser support + + For more information and a list of additional resources, please visit this [discussion](#). --- @@ -82,6 +85,7 @@ For more information and a list of additional resources, please visit this [disc
  • Running the Project Locally
    • +
  • Writing test cases
  • Deployment
    • @@ -112,7 +116,6 @@ The Dataverse Project is an open source web application to share, preserve, cite The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations and utilize the JavaScript framework of their choice. - **The goals of Dataverse Frontend:** - Modernize the application @@ -134,7 +137,7 @@ The Dataverse Frontend repository is an initiative undertaken in 2023 to moderni - Cypress testing automation - Storybook for UI Component Library -*** +--- ### Beta Testing Environment @@ -148,9 +151,8 @@ Environment updates are carried out automatically through GitHub actions, presen The environment is accessible through the following URLs: - - Dataverse Frontend SPA: [beta.dataverse.org/spa][dv_app_beta_spa_url] - - Dataverse JSF: [beta.dataverse.org][dv_app_beta_legacyjsf_url] - +- Dataverse Frontend SPA: [beta.dataverse.org/spa][dv_app_beta_spa_url] +- Dataverse JSF: [beta.dataverse.org][dv_app_beta_legacyjsf_url] ### How Existing Dataverse Installations May Be Affected @@ -161,40 +163,38 @@ The environment is accessible through the following URLs:
    Changes from the original Dataverse JSF application - - >### Changes From the Style Guide - > - >The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. - > - >#### Links - > - >We added an underline to links to make them accessible. - > - >#### File Labels - > - >Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies - the secondary color to the labels automatically, the color of the file label is now the global secondary color which is - a lighter shade of grey than what it used to be. - > - >We changed the citation block to be white with a colored border, to make the text in the box more accessible. - > - >### Changes in Functionality & Behavior - > - >Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. - > - >#### Dataset Files Tab Search - > - >The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. - > - >The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search options are available for all versions in the same way, homogenizing behavior, although losing the possibility of using the Solr grammar. - > - >The decision of this change is made on the assumption that Solr may not be required in the context of files tab search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that the assumption is incorrect, we will work on extending the search capabilities to support Solr. +> ### Changes From the Style Guide +> +> The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. +> +> #### Links +> +> We added an underline to links to make them accessible. +> +> #### File Labels +> +> Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies +> the secondary color to the labels automatically, the color of the file label is now the global secondary color which is +> a lighter shade of grey than what it used to be. +> +> We changed the citation block to be white with a colored border, to make the text in the box more accessible. +> +> ### Changes in Functionality & Behavior +> +> Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. +> +> #### Dataset Files Tab Search +> +> The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. +> +> The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search options are available for all versions in the same way, homogenizing behavior, although losing the possibility of using the Solr grammar. +> +> The decision of this change is made on the assumption that Solr may not be required in the context of files tab search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that the assumption is incorrect, we will work on extending the search capabilities to support Solr.

    (back to top)

    - ## Getting Started _To get a local copy up and running follow these simple example steps._ @@ -207,19 +207,20 @@ _To get a local copy up and running follow these simple example steps._ 2. **Docker**: We use Docker Desktop, but the Docker CLI will also work. 3. **Create a Copy of .npmrc**: In the project directory root, duplicate `.npmrc.example`, saving the copy as `.npmrc`. - > ```bash - > # root project directory - > cp .npmrc.example .npmrc - > ``` + > ```bash + > # root project directory + > cp .npmrc.example .npmrc + > ``` 4. **Create and Add Your Npm and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps outlined below. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url]. - > **Getting a GitHub Token** - > 1. Go to your GitHub [Personal Access Tokens][dv_docs_github_token_url] settings - > 2. Select `Generate new token (classic)` - > 3. Give the token a name and select scope `read:packages` - > 4. Copy the generated token and replace the string `YOUR_GITHUB_AUTH_TOKEN` in the previously created `.npmrc` file. - > Now, you should be able to install the [Dataverse JavaScript][dv_repo_dvclientjs_url] client using npm. + > **Getting a GitHub Token** + > + > 1. Go to your GitHub [Personal Access Tokens][dv_docs_github_token_url] settings + > 2. Select `Generate new token (classic)` + > 3. Give the token a name and select scope `read:packages` + > 4. Copy the generated token and replace the string `YOUR_GITHUB_AUTH_TOKEN` in the previously created `.npmrc` file. + > Now, you should be able to install the [Dataverse JavaScript][dv_repo_dvclientjs_url] client using npm. Afterwards, your .npmrc file should resemble the following: @@ -232,6 +233,7 @@ legacy-peer-deps=true //npm.pkg.github.com/:_authToken= @iqss:registry=https://npm.pkg.github.com/ ``` +
    ### Installation & Setup @@ -243,12 +245,12 @@ legacy-peer-deps=true npm install ``` + > [!WARNING] > You may see a message about vulnerabilities after running this command. > > Please check this announcement from Create React App repository [facebook/create-react-app#11174][_uses_repo_cra_error_url]. These vulnerabilities will not be included in the production build since they come from libraries only used during development. - 2. Build the UI Library, needed for running the application. ```bash @@ -256,8 +258,6 @@ npm install cd packages/design-system && npm run build ``` - - **Running & Building the App:** Run the app in the development mode. Open [http://localhost:5173][dv_app_localhost_build_url] to view it in your browser. @@ -270,7 +270,6 @@ npm start The application will actively watch the directory for changes and reload when changes are saved. You may also see any existing linting errors in the console. - ```bash # root project directory @@ -281,6 +280,7 @@ npm run build npm run preview ``` +
    **Storybook:** @@ -288,6 +288,7 @@ npm run preview Runs the Storybook in the development mode. There are 2 Storybook instances, one for the general Design System and one for the Dataverse Frontend component specifications. Both should be started automatically and available at: + - Dataverse Frontend Storybook: [http://localhost:6006/][dv_app_localhost_storybook_url] - Dataverse Design System Storybook: [http://localhost:6007/][dv_app_localhost_designsystem_url] @@ -303,6 +304,7 @@ npm run build-storybook ``` Note that both Storybook instances are also published to Chromatic as part of the build and merge processes, located at: + - [DataverseFrontend-Chromatic](https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd) - [DataverseDesignSystem-Chromatic](https://www.chromatic.com/builds?appId=646fbe232a8d3b501a1943f3) @@ -325,44 +327,43 @@ npm run cy:open-e2e [cy:open-unit] npm run test:coverage ``` +
    Using `grep` with Cypress ->The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. -> ->Some examples used by the grep library are below for reference: +> The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. > ->```bash -># root project directory +> Some examples used by the grep library are below for reference: > -># run only the tests with "auth user" in the title ->$ npx cypress run --env grep="auth user" +> ```bash +> # root project directory > -># run tests with "hello" or "auth user" in their titles by separating them with ";" character ->$ npx cypress run --env grep="hello; auth user" ->``` +> # run only the tests with "auth user" in the title +> $ npx cypress run --env grep="auth user" > ->To target specific tests, add `--spec` argument +> # run tests with "hello" or "auth user" in their titles by separating them with ";" character +> $ npx cypress run --env grep="hello; auth user" +> ``` > ->```bash -># root project directory +> To target specific tests, add `--spec` argument > ->$ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" ->\ --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx ->``` +> ```bash +> # root project directory > +> $ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" +> \ --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +> ``` > ->**Repeat and burn tests** ->You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in the spec A five times using: +> **Repeat and burn tests** +> You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in the spec A five times using: > ->```bash -># root project directory -> ->$ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx ->``` +> ```bash +> # root project directory > +> $ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +> ```
    @@ -387,7 +388,6 @@ Launch the prettier formatter. We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings][dv_repo_vscode_url] on GitHub. - ```bash # root project directory @@ -421,11 +421,13 @@ $ ./run-env.sh # Removes the project and its dependencies $ ./rm-env.sh ``` + Note that the image tag in the docker registry must to be pre pushed, otherwise the script will fail. You can find the existing tags on DockerHub [@gdcc/dataverse][dv_app_docker_image_url] If you are running the script for the first time, it may take a while, since npm has to install all project dependencies. This can also happen if you added new dependencies to `package.json`, or used the _uninstall_ script to remove current project files and shut down any running containers. Once the script has finished, you will be able to access Dataverse via: + - Dataverse SPA Frontend: [http://localhost:8000/spa][dv_app_localhost_spa_url] - Dataverse JSF Application: [http://localhost:8000][dv_app_localhost_legacy_url] @@ -442,10 +444,256 @@ If you want to add test data (collections and datasets) to the Dataverse instanc $ ./add-env-data.sh ``` + Note: The above command uses the [dataverse-sample-data][dv_repo_dvsampledata_url] repository whose scripts occasionally fail, so some of the test data may not be added.
    +## Writing test cases + +Testing is a crucial part of the SPA development. Our React application employs three main types of tests: Unit tests, +Integration tests, and End-to-End (e2e) tests. In this section, we'll describe each type of test and how to implement them. + +### 1. **Unit Tests or Component tests:** + +Unit tests are designed to test individual React components in isolation. In our approach, we focus on testing components +from the user's perspective, following the principles of the Testing Library. This means: + +- **Test What Users See:** Focus on the output of the components, such as text, interactions, and the DOM, rather than + internal implementation details like classes or functions. +- **Exceptions to the Rule:** In complex scenarios or where performance is a critical factor, we might test implementation + details to ensure a repository is correctly called, for example. However, these cases are exceptions, and the primary + goal remains on user-centric testing. +- **Avoid Testing Implementation Details:** Avoid testing implementation details like internal state or methods, as these + tests are more brittle and less valuable than user-centric tests. +- **Mocking:** We use mocks to isolate components from their dependencies, ensuring that tests are focused on the component + itself and not on its dependencies. +- **Tools and Frameworks:** We use [Cypress Component testing](https://docs.cypress.io/guides/component-testing/overview) + alongside [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to render components in + isolation and test their behavior. + +
    +Example of a Unit Test + +```javascript +//tests/component/sections/home/Home.spec.tsx + +import { Home } from '../../../../src/sections/home/Home' +import { DatasetRepository } from '../../../../src/dataset/domain/repositories/DatasetRepository' +import { DatasetPreviewMother } from '../../dataset/domain/models/DatasetPreviewMother' + +const datasetRepository: DatasetRepository = {} as DatasetRepository +const totalDatasetsCount = 10 +const datasets = DatasetPreviewMother.createMany(totalDatasetsCount) +describe('Home page', () => { + beforeEach(() => { + datasetRepository.getAll = cy.stub().resolves(datasets) + datasetRepository.getTotalDatasetsCount = cy.stub().resolves(totalDatasetsCount) + }) + + it('renders Root title', () => { + cy.customMount() + cy.findByRole('heading').should('contain.text', 'Root') + }) +}) +``` + +
    + +### 2. **Integration Tests:** + +Test the integration of the SPA with external systems, such as APIs, third-party +libraries (like js-dataverse), or databases. This ensures that the application communicates correctly with outside +resources and services. + +- **External Integrations:** Test the integration of the SPA with external systems, such as APIs, third-party + libraries (like [js-dataverse](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript/97068340)), or databases. +- **Tools and Frameworks:** We use Cypress for integration tests, to test the repository's implementation. + +
    +Example of an Integration Test + +```javascript +//tests/e2e-integration/integration/datasets/DatasetJSDataverseRepository.spec.ts + +describe('Dataset JSDataverse Repository', () => { + before(() => TestsUtils.setup()) + beforeEach(() => { + TestsUtils.login() + }) + it('gets the dataset by persistentId', async () => { + const datasetResponse = await DatasetHelper.create() + + await datasetRepository.getByPersistentId(datasetResponse.persistentId).then((dataset) => { + if (!dataset) { + throw new Error('Dataset not found') + } + const datasetExpected = datasetData(dataset.persistentId, dataset.version.id) + + expect(dataset.license).to.deep.equal(datasetExpected.license) + expect(dataset.metadataBlocks).to.deep.equal(datasetExpected.metadataBlocks) + expect(dataset.summaryFields).to.deep.equal(datasetExpected.summaryFields) + expect(dataset.version).to.deep.equal(datasetExpected.version) + expect(dataset.metadataBlocks[0].fields.publicationDate).not.to.exist + expect(dataset.metadataBlocks[0].fields.citationDate).not.to.exist + expect(dataset.permissions).to.deep.equal(datasetExpected.permissions) + expect(dataset.locks).to.deep.equal(datasetExpected.locks) + expect(dataset.downloadUrls).to.deep.equal(datasetExpected.downloadUrls) + expect(dataset.fileDownloadSizes).to.deep.equal(datasetExpected.fileDownloadSizes) + }) + }) +}) +``` + +
    + +### 3. **End-to-End (e2e) Tests:** + +End-to-end tests simulate real user scenarios, covering the complete flow of the application: + +- **User Workflows:** Focus on common user paths, like searching for a file, logging in, or creating a Dataset. Ensure + these workflows work from start to finish. +- **Avoid Redundancy:** Do not replicate tests covered by unit tests. E2E tests should cover broader user experiences. + It is important to note that e2e tests are slower and more brittle than unit tests, so we use them sparingly. +- **Tools and Frameworks:** We use Cypress for e2e tests, to test the application's behavior from the user's perspective. + It allows us to simulate user interactions and test the application's behavior in a real-world scenario. + +
    +Example of an E2E Test + +```javascript +//tests/e2e-integration/e2e/sections/create-dataset/CreateDatasetForm.spec.tsx + +describe('Create Dataset', () => { + before(() => { + TestsUtils.setup() + }) + beforeEach(() => { + TestsUtils.login() + }) + + it('navigates to the new dataset after submitting a valid form', () => { + cy.visit('/spa/datasets/create') + + cy.findByLabelText(/Title/i).type('Test Dataset Title') + cy.findByLabelText(/Author Name/i).type('Test author name', { force: true }) + cy.findByLabelText(/Point of Contact E-mail/i).type('email@test.com') + cy.findByLabelText(/Description Text/i).type('Test description text') + cy.findByLabelText(/Arts and Humanities/i).check() + + cy.findByText(/Save Dataset/i).click() + + cy.findByRole('heading', { name: 'Test Dataset Title' }).should('exist') + cy.findByText(DatasetLabelValue.DRAFT).should('exist') + cy.findByText(DatasetLabelValue.UNPUBLISHED).should('exist') + }) +}) +``` + +
    + +### Patterns and Conventions + +#### **Folder Structure** + +We have a `tests` folder in the root of the project, with subfolders for each type of test (component, +integration, e2e). The folders for integration and e2e are together in the `e2e-integration` folder. We follow the same +structure that we use for the application. + +#### **Test Naming** + +We use the same naming conventions as the application, with the suffix `.spec`. + +#### **Test Data for unit tests** + +We use [faker](https://www.npmjs.com/package/@faker-js/faker) to create test data for unit tests. This library allows us +to generate realistic and varied test data with minimal effort. We use it to create random strings, numbers, and other +values, ensuring that tests cover a wide range of cases without introducing unpredictable failures. + +**[Object Mother Pattern](https://martinfowler.com/bliki/ObjectMother.html)** + +We use the Object Mother pattern to create test data for unit tests. These classes are located in the `tests/component` +folder. + +The primary goal of the Object Mother pattern is to simplify the creation and management of test objects. It serves as a +centralized place where test objects are defined, making the testing process more streamlined and less error-prone. In this +pattern, we create a class or a set of functions dedicated solely to constructing and configuring objects needed for tests. + +Some benefits of this pattern are: + +- **Consistency:** It ensures consistent object setup across different tests, improving test reliability. +- **Readability:** It makes tests more readable and understandable by hiding complex object creation details. +- **Flexibility:** It allows us to create test data with different values and configurations. +- **Reusability:** It allows for the reuse of object configurations, reducing code duplication and saving time +- **Maintainability:** It centralizes object creation, making tests easier to maintain and update when object structures change. +- **Simplicity:** It simplifies test setup, allowing testers to focus more on the test logic than on object configuration. +- **Controlled Randomness:** It allows creating realistic and varied test scenarios while maintaining control over the randomness. + This ensures tests cover a wide range of cases without introducing unpredictable failures. + +
    +Example of an Object Mother class + +```javascript +//tests/component/dataset/domain/models/DatasetMother.ts + +export class DatasetMother { + static create(props?: Partial): Dataset { + return { + id: faker.datatype.uuid(), + title: faker.lorem.words(3), + ...props + } + } +} +``` + +
    + +#### **Test Data for integration and e2e tests** + +We use some helper classes to create test data for the integration and e2e tests. These classes are located in the +`tests/e2e-integration/shared` folder. + +The test data is created using [axios](https://www.npmjs.com/package/axios), which allows us to make requests to the +Dataverse API and create test data for the integration and e2e tests. + +
    +Example of a Helper class to create test data + +```javascript +//tests/e2e-integration/shared/datasets/DatasetHelper.ts +export class DatasetHelper extends DataverseApiHelper { + static async create(): Promise { + return this.request < DatasetResponse > (`/dataverses/root/datasets`, 'POST', newDatasetData) + } +} +``` + +
    + +#### **Test Organization** + +We organize tests into suites, grouping them by feature or user workflow. This makes it easier to find and run tests. + +#### **Test Isolation** + +We aim to keep tests as isolated as possible, avoiding dependencies between tests and ensuring that each test can run +independently. + +### Continuous Integration (CI) + +We run tests on every pull request and merge to ensure that the application is always stable and functional. You can +find the CI workflow in the `.github/workflows/test.yml` file. + +### Test coverage + +We aim for high test coverage, especially in critical areas of the application, like user workflows +or complex components. However, we prioritize user-centric testing over coverage numbers. The threshold for test coverage +is 95%. It only includes the coverage of the unit tests. + +

    (back to top)

    +
    + ### Deployment Once the site is built through the `npm run build` command, it can be deployed in different ways to different types of infrastructure, depending the needs of the installation. @@ -454,7 +702,6 @@ We are working to provide different preconfigured automated deployment options, The current automated deployment options are available within the GitHub `deploy` workflow, which is designed to be run manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment. -
    Examples for AWS and Payara @@ -464,37 +711,33 @@ This option will build and deploy the application to a remote S3 bucket. For this workflow to work, a GitHub environment must be configured with the following environment secrets: - - `AWS_ACCESS_KEY_ID` - - `AWS_SECRET_ACCESS_KEY` - - `AWS_S3_BUCKET_NAME` - - `AWS_DEFAULT_REGION` +- `AWS_ACCESS_KEY_ID` +- `AWS_SECRET_ACCESS_KEY` +- `AWS_S3_BUCKET_NAME` +- `AWS_DEFAULT_REGION` Note that for the deployment to the S3 bucket to succeed, you must make the following changes to the bucket via the S3 web interface (or equivalent changes using aws-cli or similar tools): - - Under _`Permissions`_ ⏵ _`Permissions Overview`_ ⏵ _`Block public access (bucket settings)`_ ⏵ click _`Edit`_, then __uncheck__ _`Block all public access`_ and save. - - Under _`Properties`_ ⏵ _`Static website hosting`_ ⏵ click _`Edit`_ and enable it. Change _`Index document`_ and _`Error document`_ to `index.html`. - - Under _`Bucket Policy`_, click _`Edit`_ and paste the following policy (changing `` to your bucket name) and save. +- Under _`Permissions`_ ⏵ _`Permissions Overview`_ ⏵ _`Block public access (bucket settings)`_ ⏵ click _`Edit`_, then **uncheck** _`Block all public access`_ and save. +- Under _`Properties`_ ⏵ _`Static website hosting`_ ⏵ click _`Edit`_ and enable it. Change _`Index document`_ and _`Error document`_ to `index.html`. +- Under _`Bucket Policy`_, click _`Edit`_ and paste the following policy (changing `` to your bucket name) and save. ```json { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "PublicReadGetObject", - "Principal": "*", - "Effect": "Allow", - "Action": [ - "s3:GetObject" - ], - "Resource": [ - "arn:aws:s3:::/*" - ] - } - ] + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "PublicReadGetObject", + "Principal": "*", + "Effect": "Allow", + "Action": ["s3:GetObject"], + "Resource": ["arn:aws:s3:::/*"] + } + ] } ``` -You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; `http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` +You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; `http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` #### Deployment with Payara @@ -504,9 +747,9 @@ This option is intended for an "all-in-one" solution, where the Dataverse backen For this workflow to work, a GitHub environment must be configured with the following environment secrets: - - `PAYARA_INSTANCE_HOST` - - `PAYARA_INSTANCE_USERNAME` - - `PAYARA_INSTANCE_SSH_PRIVATE_KEY` +- `PAYARA_INSTANCE_HOST` +- `PAYARA_INSTANCE_USERNAME` +- `PAYARA_INSTANCE_SSH_PRIVATE_KEY` It is important that the remote instance is correctly pre-configured, with the Payara server running, and a service account for Dataverse with the corresponding SSH key pair established. @@ -517,18 +760,16 @@ A base path for the frontend application can be established on the remote server

    (back to top)


    - ## Usage Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. _For more examples, please refer to the [Documentation][dv_docs_devs_url]_ - - This project uses Atomic Design for it's Components. Here are several resources for Atomic Design if you are unfamiliar: + @@ -564,6 +805,7 @@ If you have a suggestion that would make this better, please fork the repo and c Got Questions? Join the conversation on [Zulip][dv_community_zulip_url], or our Google Groups for [Developers][dv_community_google_devs_url] and [Users][dv_community_google_users_url]. Or attend community meetings, hosted by the The Global Dataverse Community Consortium to collaborate with the interest groups for [Frontend Development][dv_community_gdcc_ui_url] and [Containerization][dv_community_gdcc_containers_url], learn and share with communities around the world! + Find videos and release overviews on our YouTube Channel, and check out the resources on our [website][dv_docs_dataverse_url].

    (back to top)

    @@ -572,7 +814,6 @@ Find videos and release overviews on our YouTube Channel, and check out the reso - ## Contact Email us with software installation questions. Please note our response time is generally 24 business hours. @@ -588,12 +829,9 @@ Report bugs and add feature requests in GitHub Issues or use GitHub pull request Ask a question or start a discussion: A great place to publicly share feedback, ideas, feature requests, and troubleshoot any issues is in the dataverse-community mailing list. Additional mailing lists are available, including language-specific ones. - -

    (back to top)


    - ## Acknowledgments Chromatic @@ -603,7 +841,7 @@ Thanks to [Chromatic][_uses_chromatic_url] for providing the visual testing plat

    (back to top)


    -*** +--- ### Built With @@ -612,7 +850,7 @@ This section should list any major frameworks/libraries used to bootstrap your p

    (back to top)


    -*** +--- ## License @@ -621,14 +859,13 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform

    (back to top)


    - - + [dv_repo_url]: https://github.com/IQSS/dataverse-frontend [dv_repo_issues_url]: https://github.com/IQSS/dataverse-frontend/issues [dv_repo_sprint_url]: https://github.com/orgs/IQSS/projects/34/views/23 @@ -643,6 +880,7 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [dv_repo_dvclientjs_url]: https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript [dv_repo_dvclientjs_npm_url]: https://www.npmjs.com/package/js-dataverse [dv_repo_dvsampledata_url]: https://github.com/IQSS/dataverse-sample-data @@ -653,6 +891,7 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [dv_app_beta_spa_url]: https://beta.dataverse.org/spa [dv_app_beta_legacyjsf_url]: https://beta.dataverse.org [dv_app_legacyjsf_demo_url]: https://demo.dataverse.org/ @@ -661,11 +900,14 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform [dv_app_localhost_designsystem_url]: http://localhost:6007/ [dv_app_localhost_spa_url]: http://localhost:8000/spa [dv_app_localhost_legacy_url]: http://localhost:8000/ + + [dv_app_docker_image_url]: https://hub.docker.com/r/gdcc/dataverse/tags + [dv_community_gdcc_url]: https://www.gdcc.io/ [dv_community_gdcc_ui_url]: https://ui.gdcc.io/ [dv_community_gdcc_containers_url]: https://ct.gdcc.io/ @@ -675,12 +917,14 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [hvd_iqss_url]: https://www.iq.harvard.edu/ [hvd_iqss_roadmap_url]: https://www.iq.harvard.edu/roadmap-dataverse-project [hvd_legacyjsf_url]: https://dataverse.harvard.edu/ + [dv_docs_dataverse_url]: https://dataverse.org/ [dv_docs_about_url]: https://dataverse.org/about [dv_docs_styleguide_url]: https://guides.dataverse.org/en/latest/style/index.html @@ -691,6 +935,7 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [_uses_reactjs_url]: https://reactjs.org/ [_uses_nodejs_url]: https://nodejs.org/ [_uses_typescript_url]: https://typescriptlang.org/ @@ -704,12 +949,16 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform [_uses_chromatic_url]: https://www.chromatic.com/ [_uses_repo_cra_error_url]: https://github.com/facebook/create-react-app/issues/11174 [_uses_tool_chromatic_url]: https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd + + [_uses_lib_grep_url]: https://www.npmjs.com/package/@cypress/grep + + [_shield_reactjs]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB [_shield_nodejs]: https://img.shields.io/badge/node.js-000000?style=for-the-badge&logo=nodedotjs&logoColor=white [_shield_typescript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white @@ -722,12 +971,16 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform [_shield_zulip]: https://img.shields.io/badge/zulip-chat?style=for-the-badge&logo=zulip&logoColor=%236492FE [_shield_googledevs]: https://img.shields.io/badge/Developer_Group-white?style=for-the-badge&logo=google [_shield_googleusers]: https://img.shields.io/badge/User_Group-white?style=for-the-badge&logo=google + + [_shield_projectstatus]: https://img.shields.io/badge/repo_status-WIP-yellow?style=for-the-badge [_shield_contributors]: https://img.shields.io/github/contributors/IQSS/dataverse-frontend?branch=develop&style=for-the-badge [_shield_stargazers]: https://img.shields.io/github/stars/iqss/dataverse-frontend?style=for-the-badge [_shield_coveralls]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge + + [_shield_workflow]: https://img.shields.io/github/actions/workflow/status/IQSS/dataverse-frontend/test.yml?branch=develop&style=for-the-badge [_shield_issues]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge [_shield_forks]: https://img.shields.io/github/forks/IQSS/dataverse-frontend?style=for-the-badge @@ -735,18 +988,24 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [_img_dv_logo_withbackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6986476f-39ba-46a4-9be0-f05cd8e92244 [_img_dv_logo_nobackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6c4d79e4-7be5-4102-88bd-dfa167dc79d3 [_img_screenshot]: images/screenshot.png + [_video_demo_datasetpage_url]: https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ + + [_video_demo_filetable_url]: https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ + [_social_twitter]: https://twitter.com/your_username + From abbd345af3eb550ef93a444ac5ab4e09c3dc671a Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 19 Mar 2024 10:37:51 +0100 Subject: [PATCH 10/26] feat(Developer Guide): add Coverage section --- README.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7c81a7d48..4744f7667 100644 --- a/README.md +++ b/README.md @@ -331,7 +331,7 @@ npm run test:coverage
    -Using `grep` with Cypress +Running specific tests > The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. > @@ -687,9 +687,36 @@ find the CI workflow in the `.github/workflows/test.yml` file. ### Test coverage -We aim for high test coverage, especially in critical areas of the application, like user workflows -or complex components. However, we prioritize user-centric testing over coverage numbers. The threshold for test coverage -is 95%. It only includes the coverage of the unit tests. +We aim for high test coverage, especially in critical areas of the application, like user workflows or complex components. +However, we prioritize user-centric testing over coverage numbers. + +- **Coverage Threshold:** We aim for a test coverage of 95% for the unit tests. This threshold is set in the `.nycrc.json` file. +- **Coverage Reports:** We use [nyc](https://www.npmjs.com/package/nyc) to generate coverage reports, which are available +in the `coverage` folder after running the tests. These reports are also published to [Coveralls](https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop) +with every pull request and merge. The coverage badge is displayed at the top of the README. +- **Tests included in the coverage:** We include all unit tests in the coverage report. +- **Pre-commit hook:** We use [pre-commit](https://www.npmjs.com/package/pre-commit) to run the unit tests before every commit, +ensuring that no code is committed without passing the tests. It also runs the coverage checks to ensure that the coverage +threshold is met. + +#### How to run the code coverage + +To generate the code coverage, you first need to run the tests with the `test:unit` script. After running the tests, you +can check the coverage with the `test:coverage` script. + +If you want to see the coverage report in the browser, you can open the `coverage/lcov-report/index.html` file in the browser. + +```bash +# root project directory + +# Run the unit tests and generate the coverage report + +npm run test:unit + +# Check the coverage + +npm run test:coverage +```

    (back to top)


    From 1220a7d865f3a0031e8fa8449265855f28e5200c Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 19 Mar 2024 11:07:35 +0100 Subject: [PATCH 11/26] feat(Developer Guide): add some notes about Writing test cases --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4744f7667..9d22695fb 100644 --- a/README.md +++ b/README.md @@ -547,6 +547,28 @@ describe('Dataset JSDataverse Repository', () => {
    +
    +Wait for no locks + +Some integration tests require waiting for no locks to be present in the dataset. This is done using the `waitForNoLocks` +method from the `TestsUtils` class. + +```javascript +it('waits for no locks', async () => { + const datasetResponse = await DatasetHelper.create() + + await DatasetHelper.publish(datasetResponse.persistentId) + await TestsUtils.waitForNoLocks(datasetResponse.persistentId) + + await datasetRepository.getByPersistentId(datasetResponse.persistentId).then((dataset) => { + if (!dataset) { + throw new Error('Dataset not found') + } + expect(dataset.locks).to.deep.equal([]) + }) +}) +``` + ### 3. **End-to-End (e2e) Tests:** End-to-end tests simulate real user scenarios, covering the complete flow of the application: @@ -590,7 +612,13 @@ describe('Create Dataset', () => { }) ``` -
    +> **Note:** The current e2e tests are failing due to the following reasons: +> +> - **Dataset JSDataverse Repository -> gets the total dataset count**: Calling `destroyAll()` before the "gets the total +> - dataset count" test in `DatasetJSDataverseRepository.spec.ts` causes an optimistic lock exception in Dataverse. +> +> **Solution:** We need to either reset the database after each test or find an alternative method to avoid the optimistic +> lock exception. Check the issue [here](https://github.com/IQSS/dataverse-frontend/issues/294). ### Patterns and Conventions @@ -685,6 +713,17 @@ independently. We run tests on every pull request and merge to ensure that the application is always stable and functional. You can find the CI workflow in the `.github/workflows/test.yml` file. +CI checks include: + +- **Unit Tests:** We run all unit tests to ensure that the application's components work as expected. +- **Integration Tests:** We run integration tests to ensure that the application communicates correctly with external + systems. +- **E2E Tests:** We run e2e tests to ensure that the application's behavior is correct from the user's perspective. +- **Accessibility Tests:** We run checks to ensure that the application is accessible and that it meets the highest standards + for accessibility compliance. +- **Code Coverage:** We check the test coverage to ensure that the application is well-tested and that new code is + covered by tests. + ### Test coverage We aim for high test coverage, especially in critical areas of the application, like user workflows or complex components. @@ -692,12 +731,12 @@ However, we prioritize user-centric testing over coverage numbers. - **Coverage Threshold:** We aim for a test coverage of 95% for the unit tests. This threshold is set in the `.nycrc.json` file. - **Coverage Reports:** We use [nyc](https://www.npmjs.com/package/nyc) to generate coverage reports, which are available -in the `coverage` folder after running the tests. These reports are also published to [Coveralls](https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop) -with every pull request and merge. The coverage badge is displayed at the top of the README. + in the `coverage` folder after running the tests. These reports are also published to [Coveralls](https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop) + with every pull request and merge. The coverage badge is displayed at the top of the README. - **Tests included in the coverage:** We include all unit tests in the coverage report. - **Pre-commit hook:** We use [pre-commit](https://www.npmjs.com/package/pre-commit) to run the unit tests before every commit, -ensuring that no code is committed without passing the tests. It also runs the coverage checks to ensure that the coverage -threshold is met. + ensuring that no code is committed without passing the tests. It also runs the coverage checks to ensure that the coverage + threshold is met. #### How to run the code coverage From b509e4a93f4e5203469925c284d7eed2e2f0c67d Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 25 Mar 2024 13:53:24 +0100 Subject: [PATCH 12/26] feat(Developer Guide): move React Testing Library link --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9d22695fb..2e9d8d17d 100644 --- a/README.md +++ b/README.md @@ -457,7 +457,8 @@ Integration tests, and End-to-End (e2e) tests. In this section, we'll describe e ### 1. **Unit Tests or Component tests:** Unit tests are designed to test individual React components in isolation. In our approach, we focus on testing components -from the user's perspective, following the principles of the Testing Library. This means: +from the user's perspective, following the principles of the [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/). +This means: - **Test What Users See:** Focus on the output of the components, such as text, interactions, and the DOM, rather than internal implementation details like classes or functions. @@ -469,8 +470,7 @@ from the user's perspective, following the principles of the Testing Library. Th - **Mocking:** We use mocks to isolate components from their dependencies, ensuring that tests are focused on the component itself and not on its dependencies. - **Tools and Frameworks:** We use [Cypress Component testing](https://docs.cypress.io/guides/component-testing/overview) - alongside [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to render components in - isolation and test their behavior. + alongside React Testing Library to render components in isolation and test their behavior.
    Example of a Unit Test From 6d2c130197af30465a2fea9d4f4a81df659b0888 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 25 Mar 2024 13:56:40 +0100 Subject: [PATCH 13/26] feat(Developer Guide): add missing details closing tag --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 2e9d8d17d..68d039aaa 100644 --- a/README.md +++ b/README.md @@ -569,6 +569,8 @@ it('waits for no locks', async () => { }) ``` +
    + ### 3. **End-to-End (e2e) Tests:** End-to-end tests simulate real user scenarios, covering the complete flow of the application: From 89713d6843bb2732269d87a90556969a3d03333e Mon Sep 17 00:00:00 2001 From: MellyGray Date: Wed, 27 Mar 2024 15:46:57 +0100 Subject: [PATCH 14/26] feat(Frontend Guides): add the same CODE_OF_CONDUCT as the main Dataverse repo --- CODE_OF_CONDUCT.md | 170 ++++++++++++++------------------------------- 1 file changed, 52 insertions(+), 118 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index b4434fdfe..70a654f0e 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,142 +1,76 @@ -# Dataverse® Code of Conduct +# Contributor Covenant Code of Conduct ## Our Pledge -[Institute for Quantitative Social Science](http://www.iq.harvard.edu/) (IQSS) - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. +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, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. ## Our Standards -Examples of behavior that contributes to a positive environment for our -community include: - -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -- Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -- The use of sexualized language or imagery, and sexual attention or - advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email - address, without their explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Scope - -We expect everyone on the IQSS Dataverse team, and those contributing to our open source community, to exhibit -these behaviors and abide by applicable federal laws and Harvard University policies. +Examples of behavior that contributes to creating a positive environment +include: -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. +* 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 -## What We Strive For +Examples of unacceptable behavior by participants include: -At IQSS, we strive to create a welcoming and inclusive culture that empowers people to share, preserve, cite, explore, and analyze research data. That kind of atmosphere requires an open exchange of ideas balanced by thoughtful guidelines. Examples of behavior that contributes to a positive environment for our open source community 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 -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -- Focusing on what is best not just for us as individuals, but for the overall community and public +## Our Responsibilities -## Enforcement Responsibilities +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. -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. +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. -Community leaders 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, and will communicate reasons for moderation -decisions when appropriate. +## Scope -## Enforcement Guidelines +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 to the community leaders responsible for enforcement at IQSS (EMAIL). -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction +reported by contacting the project team at support at dataverse dot org. 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. -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. +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 -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html [homepage]: https://www.contributor-covenant.org -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq \ No newline at end of file From 37cbd329d4359253df4d4290bc9d29eb0848cabf Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 10:06:54 +0200 Subject: [PATCH 15/26] feat(Frontend Guides): address all TODOs from the CONTRIBUTING.md file --- CONTRIBUTING.md | 193 +++++++++++++++++++++++++++++++----------------- 1 file changed, 125 insertions(+), 68 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43f6b1790..ea9ee946b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,72 +5,122 @@ > feature request, you are agreeing to comply with this waiver of copyright interest. > Details can be found in our [LICENSE](LICENSE). -Hey there! We’re really happy you’ve found your way here. Dataverse® is a community project that is developed by people from all over the world. We appreciate any help. +Thank you for your interest in contributing to Dataverse Frontend! We are open to contributions from everyone. You don't +need permission to participate. Just jump in. If you have questions, please reach out using one or more of the channels +described below. -Before you start working on something we would suggest talking to us in the [TODO: discussion forum](#) or asking a question on [TODO: GoogleGroups/Zulip](#). You can also contact us via the chat widget on the [TODO: main Dataverse website](#). +We aren't just looking for developers. There are many ways to contribute to Dataverse. We welcome contributions +of ideas, bug reports, usability research/feedback, documentation, code, and more! Please, check the [Dataverse main repo] +for more information on how to contribute to the Dataverse project. Here are ways to get involved: -1. [Star](https://github.com/iqss/dataverse-frontend/stargazers) the project! -2. Answer questions that come in through [GitHub issues](https://github.com/iqss/dataverse-frontend/issues?state=open). -3. [Report a bug](https://github.com/iqss/dataverse-frontend/issues/new?assignees=&labels=&projects=&title=%5BBUG%5D+Your+title) that you find. -4. Share a project you’ve built with Dataverse. This helps transfer knowledge about best practices, etc. _Add it to the [TODO: Showcase list](https://github.com/iqss/dataverse-frontend/foo/wiki/Showcase)_. -5. Browse ["help wanted"](https://github.com/iqss/dataverse-frontend/labels/help%20wanted) and ["good first issue"](https://github.com/iqss/dataverse-frontend/labels/good%20first%20issue) labels for areas of Dataverse/JavaScript/code you know well to consider, build or document. -6. Answer questions on [Google Groups | posted under the «Dataverse» tag](#). You can also [TODO: subscribe to a tag](#) via email to get notified when someone needs help. -7. Answer questions and join in on [Google Groups/Zulip Discussions](#). +1. [Star] the project! +2. Answer questions and join in on [issue tracker]. +3. [Report a bug] that you find. +4. Browse ["help wanted"] and ["good first issue"] labels for areas of Dataverse/JavaScript/code you know well to consider, build or document. -## Using the issue tracker +## Bug Reports/Issues -Use the issue tracker to suggest feature requests, report bugs, and ask questions. -This is also a great way to connect with the developers of the project as well -as others who are interested in this solution. +An issue is a bug (a feature is no longer behaving the way it should) or a feature (something new to Dataverse that helps +users complete tasks). You can browse the Dataverse Frontend [issue tracker] on GitHub by open or closed issues. -Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in -the issue that you will take on that effort, then follow the _Changing the code-base_ -guidance below. +Before submitting an issue, please search the existing issues by using the search bar at the top of the page. If there +is an existing open issue that matches the issue you want to report, please add a comment to it. -## Documenting +If there is no pre-existing issue or it has been closed, please click on the "New Issue" button, log in, and write in +what the issue is (unless it is a security issue which should be reported privately to security@dataverse.org). + +If you do not receive a reply to your new issue or comment in a timely manner, please email support@dataverse.org with a link to the issue. + +### Writing an Issue -This is probably one of the most important things you can do as a contributor and probably one of the easiest things you can do. There are two big pieces of documentation you can edit right here on github! +For the subject of an issue, please start it by writing the feature or functionality it relates to, i.e. "Create Account:..." +or "Dataset Page:...". In the body of the issue, please outline the issue you are reporting with as much detail as possible. +In order for the Dataverse development team to best respond to the issue, we need as much information about the issue as +you can provide. Include steps to reproduce bugs. Indicate which version you're using, which is shown at the bottom of the page. We love screenshots! -The first is the [TODO: Readme?](https://www.codenameone.com/javadoc/) which you can edit directly in the source code, if there is an ommission or a mistake you can just press the edit button on the file and make the change directly even without an IDE. These pull requests are highly appreciated and will help future generations of developers! +### Issue Attachments -The [Dataverse developer guide](https://guides.dataverse.org/en/latest/developers/index.html) is generated from [TODO: the wiki pages of this project](https://github.com/iqss/dataverse-frontend/foo/wiki/). You can just [TODO: edit the wiki directly](#), and your changes will reflect in the developers guide. Don't forget to edit the authors section and add some credit! +You can attach certain files (images, screenshots, logs, etc.) by dragging and dropping, selecting them, or pasting from +the clipboard. Files must be one of GitHub's [supported attachment formats] such as png, gif, jpg, txt, pdf, zip, etc. +(Pro tip: A file ending in .log can be renamed to .txt, so you can upload it.) If there's no easy way to attach your file, +please include a URL that points to the file in question. -Please try to maintain the convention for the guide as we automate many pieces in the guide generation and conversion. +[supported attachment formats]: https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/ + +## Documenting + +This is probably one of the most important things you can do as a contributor and probably one of the easiest things you can do. +For the moment we only use the [README], which you can edit right here on GitHub! + +if there is a mistake you can just press the edit button on the file and make the change directly even without an IDE. +These pull requests are highly appreciated and will help future generations of developers! + +[README]: https://github.com/IQSS/dataverse-frontend/edit/develop/README.md ## Changing the code-base -Generally speaking, you should fork this repository, make changes in your -own fork, and then submit a pull request. All new code should have associated -unit tests that validate implemented features and the presence or lack of defects. -Additionally, the code should follow any stylistic and architectural guidelines -prescribed by the project. In the absence of such guidelines, mimic the styles -and patterns in the existing code-base. +If you are interested in working on the Dataverse Frontend code, great! Before you start working on something we would +suggest talking to us in the [Zulip UI Dev Stream] + +Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull request. All +new code should have associated unit tests that validate implemented features and the presence or lack of defects. +Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence +of such guidelines, mimic the styles and patterns in the existing code-base. -Pull requests are highly appreciated. More than [X people](https://github.com/iqss/dataverse/graphs/contributors) have written parts of Dataverse (so far). Here are some guidelines to help: +Pull requests are highly appreciated. More than [5 people] have written parts of Dataverse Frontend (so far). Here are some +guidelines to help: 1. **Solve a problem** – Features are great, but even better is cleaning-up and fixing issues in the code that you discover. 2. **Write tests** – This helps preserve functionality as the codebase grows and demonstrates how your change affects the code. -3. **Write documentation** – Timber is only useful if its features are documented. This covers inline documentation of the code as well as documenting functionality and use cases in the Guides section of the documentation. +3. **Write documentation** – We have a [README] that always needs updating. 4. **Small > big** – Better to have a few small pull requests that address specific parts of the code, than one big pull request that jumps all over. 5. **Comply with Coding Standards** – See next section. ## Preparations -After you’ve forked the Dataverse Frontend repository, you should install all npm dependencies. - -```bash -npm install -``` +After you’ve forked the Dataverse Frontend repository, you should follow the Getting Started instructions in the +[Getting Started Section] to get your local environment up and running. ## Coding Standards -We use [TODO: EasyCodingStandard](https://github.com/symplify/easy-coding-standard) for Dataverse’s code and code examples in the documentation, which follows the [TODO: X: Extended Coding Styles](#). +This project adheres to the following coding standards to ensure consistency, readability, and maintainability of the codebase. + +### General Principles + +- Code should be self-documenting. Choose descriptive names for variables and functions. +- Comment your code when necessary. Comments should explain the 'why' and not the 'what'. +- Keep functions small and focused. A function should ideally do one thing. +- Follow the DRY (Don't Repeat Yourself) principle. Reuse code as much as possible. But don't over-engineer, sometimes + it's better to duplicate code than to overcomplicate it. + +### TypeScript + +- Follow the [TypeScript Deep Dive Style Guide]. +- Use `PascalCase` for class names, `camelCase` for variables and functions, `UPPERCASE` for constants. +- Always specify the type when declaring variables, parameters, and return types. + +### JavaScript Standards -We use ESLint to automatically check and apply the coding standards to our codebase, reducing the manual work to a minimum. +- Use ES6+ syntax whenever possible. +- Prefer const and let to var for variable declarations. +- Use arrow functions () => {} for anonymous functions. -### Check and apply coding standards +### React Standards + +- Component Design: Prefer functional components with hooks over class components. +- State Management: Use local state (useState, useReducer) where possible and consider context or Redux for global state. +- Event Handlers: Prefix handler names with handle, e.g., handleClick. +- JSX: Keep JSX clean and readable. Split into smaller components if necessary. + +### CSS/SASS Standards + +Modularization: Store stylesheets near their respective components and import them as modules. + +### Linting + +We use ESLint to automatically check and apply the coding standards to our codebase, reducing the manual work to a minimum To run all checks, you can run the `lint` script. @@ -94,7 +144,8 @@ npm run format ### Enforcing coding standards using pre-commit hooks -We use [TODO: XX](#) to add pre-commit hooks which automatically check the committed code changes for any coding standard violations. +We use [pre-commit] library to add pre-commit hooks which automatically check the committed +code changes for any coding standard violations. ### Tests @@ -105,35 +156,41 @@ You can check the coverage with `npm run test:coverage` `npm run test:e2e` Launches the Cypress test runner for the end-to-end tests. If you prefer to see the tests executing in cypress you can run `npm run cy:open-e2e` -### Other commands - -There are more commands that we use to ensure code quality. Usually, you won’t need them. - - - -## Process - -All PRs receive a review from at least one maintainer. We’ll do our best to do that review as soon as possible, but we’d rather go slow and get it right than merge in code with issues that just lead to trouble. - ### GitHub reviews & assignments -You might see us assign multiple reviewers, in this case these are OR checks (i.e. either Person1 or Person2) unless we explicitly say it’s an AND type thing (i.e. can both Person3 and Person4 check this out?). - -We use the assignee to show who’s responsible at that moment. We’ll assign back to the submitter if we need additional info/code/response, or it might be assigned to a branch maintainer if it needs more thought/revision (perhaps it’s directly related to an issue that's actively being worked on). - -Once approved, the lead maintainer for the branch should merge the PR into the `develop` branch. - -### Codeowners - -We use a [CODEOWNERS](https://github.com/iqss/dataverse-frontend/blob/master/.github/CODEOWNERS) file to define who gets automatic review invitations. - -## Ownership - -By contributing code you are granting _(`Dataverse`)_ shared ownership of your work. You still own it but _(`Dataverse`)_ will have the right to relicense your work based on our needs & treat this work as if it was developed by a _(`Dataverse`)_ engineer. - -## Browser support - - +All PRs receive a review from at least one maintainer. We’ll do our best to do that review as soon as possible, but we’d +rather go slow and get it right than merge in code with issues that just lead to trouble. + +You might see us assign multiple reviewers, in this case these are OR checks (i.e. either Person1 or Person2) unless we +explicitly say it’s an AND type thing (i.e. can both Person3 and Person4 check this out?). + +We use the assignee to show who’s responsible at that moment. We’ll assign back to the submitter if we need additional +info/code/response, or it might be assigned to a branch maintainer if it needs more thought/revision (perhaps it’s directly +related to an issue that's actively being worked on). + +After making your pull request, your goal should be to help it advance through our kanban board at [IQSS Dataverse Project]. +If no one has moved your pull request to the code review column in a timely manner, please reach out. Note that once a pull request +is created for an issue, we'll remove the issue from the board so that we only track one card (the pull request). + +Thanks for your contribution! + +## Other ways to contribute to the code + +We love code contributions. Developers are not limited to the Frontend Dataverse code in this git repo. You can help with +API client libraries in your favorite language that are mentioned in the [API Guide][] or create a new library. In this +repo we are using the [JavaScript Dataverse API client library] in which you can contribute to as well. + +[API Guide]: http://guides.dataverse.org/en/latest/api +[issue tracker]: https://github.com/IQSS/dataverse-frontend/issues +[Dataverse main repo]: https://github.com/IQSS/dataverse/blob/develop/CONTRIBUTING.md +[Star]: https://github.com/iqss/dataverse-frontend/stargazers +[Report a bug]: https://github.com/iqss/dataverse-frontend/issues/new?assignees=&labels=&projects=&title=%5BBUG%5D+Your+title +["help wanted"]: https://github.com/iqss/dataverse-frontend/labels/help%20wanted: +["good first issue"]: https://github.com/iqss/dataverse-frontend/labels/good%20first%20issue +[Zulip UI Dev Stream]: https://dataverse.zulipchat.com/#narrow/stream/410361-ui-dev +[5 people]: https://github.com/iqss/dataverse-frontend/graphs/contributors +[Getting Started Section]: https://github.com/IQSS/dataverse-frontend?tab=readme-ov-file#getting-started +[TypeScript Deep Dive Style Guide]: https://basarat.gitbook.io/typescript/styleguide +[pre-commit]: https://www.npmjs.com/package/pre-commit +[IQSS Dataverse Project]: https://github.com/orgs/IQSS/projects/34 +[JavaScript Dataverse API client library]: https://github.com/IQSS/dataverse-client-javascript From ea6a12a6aa49d569f222bb9b9b9a65ce856085e0 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 11:44:34 +0200 Subject: [PATCH 16/26] feat(Frontend Guides): address all TODOs in the README --- README.md | 442 +++++++++++++++++++++++++++--------------------------- 1 file changed, 223 insertions(+), 219 deletions(-) diff --git a/README.md b/README.md index bec0b8830..a8bae2a06 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ - - - - [![CI][_shield_projectstatus]][dv_repo_projectstatus_url] [![CI][_shield_contributors]][dv_repo_contributors_url] [![CI][_shield_stargazers]][dv_repo_stargazers_url] @@ -11,6 +7,7 @@ [![CI][_shield_forks]][dv_repo_forks_url] + -For more information and a list of additional resources, please visit this [discussion](#). +To stay up-to-date with all the latest changes, join the [Google Group][dv_community_google_users_url] --- - -
    - Table of Contents +## Table of Contents +
    1. About The Project @@ -83,46 +79,43 @@ For more information and a list of additional resources, please visit this [disc
    2. Deployment
      3. - - -
    3. Roadmap
    4. Contributing
    5. License
    6. Contact
    7. Acknowledgments
    -
    - +--- ## About the Project -[![Product Name Screen Shot][_img_screenshot]][_img_screenshot] - ---- - ### What is Dataverse? -The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. Read more on the [Dataverse Website][dv_docs_dataverse_url]. +The Dataverse Project is an open source web application to share, preserve, cite, explore, and analyze research data. It +facilitates making data available to others, and allows you to replicate others' work more easily. Researchers, journals, +data authors, publishers, data distributors, and affiliated institutions all receive academic credit and web visibility. +Read more on the [Dataverse Website][dv_docs_dataverse_url]. ### What is Dataverse Frontend _& How is it different?_ -The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations and utilize the JavaScript framework of their choice. - +The Dataverse Frontend repository is an initiative undertaken in 2023 to modernize the UI and design of the Dataverse +Project by creating a stand-alone interface to allow users and organizations to implement their own Dataverse installations +and utilize the JavaScript framework of their choice. **The goals of Dataverse Frontend:** - Modernize the application - Separate the frontend and backend logic, transition away from Monolithic Architecture -- Reimagine the current Dataverse backend as a headess API-first instance. +- Reimagine the current Dataverse backend as a headless API-first instance. - The Dataverse Frontend becomes a stand-alone SPA (Single Page Application) - Modularize the UI to allow third-party extension of the base project - Increase cadence of development, decrease time between release cycles to implement new features - Introduce testing automation -- Give priority and transparency to coding and design to support Harvard University's commitment to ensuring the highest standards for Accessibility Compliance +- Give priority and transparency to coding and design to support Harvard University's commitment to ensuring the highest + standards for Accessibility Compliance - Empower the community to create, contribute, and improve. **New Features:** @@ -134,67 +127,78 @@ The Dataverse Frontend repository is an initiative undertaken in 2023 to moderni - Cypress testing automation - Storybook for UI Component Library -*** +--- ### Beta Testing Environment _Track our progress and compare it to the current Dataverse application!_ -To make the SPA Frontend accesible and testable by people interested in the project, there is a remote beta testing environment that includes the latest changes developed both for the frontend application and the Dataverse backend application (develop branches). +To make the SPA Frontend accessible and testable by people interested in the project, there is a remote beta testing +environment that includes the latest changes developed both for the frontend application and the Dataverse backend +application (develop branches). This environment follows the "all-in-one" solution described above, where both applications coexist on a Payara server. -Environment updates are carried out automatically through GitHub actions, present both in this repository and in the Dataverse backend repository, which deploy the develop branches when any change is pushed to them. +Environment updates are carried out automatically through GitHub actions, present both in this repository and in the +Dataverse backend repository, which deploy the develop branches when any change is pushed to them. The environment is accessible through the following URLs: - - Dataverse Frontend SPA: [beta.dataverse.org/spa][dv_app_beta_spa_url] - - Dataverse JSF: [beta.dataverse.org][dv_app_beta_legacyjsf_url] - +- Dataverse Frontend SPA: [beta.dataverse.org/spa][dv_app_beta_spa_url] +- Dataverse JSF: [beta.dataverse.org][dv_app_beta_legacyjsf_url] ### How Existing Dataverse Installations May Be Affected -- The existing Dataverse API will be added to and extended from the present backend architecture while the existing UI and current Dataverse functionalities are preserved. +- The existing Dataverse API will be added to and extended from the present backend architecture while the existing UI + and current Dataverse functionalities are preserved. - The SPA will continue its life as a separate application, supported on its own maintenance schedule. -- When the SPA has matured enough for an official release, we will switch to the new version and the old backend (Link to repository) will be moved into maintenance mode with no new features being introduced and focusing only on critical bugfixes. +- When the SPA has matured enough for an official release, we will switch to the new version and the [old backend][dv_repo_legacyjsf_url] + will be moved into maintenance mode with no new features being introduced and focusing only on critical bugfixes.
    Changes from the original Dataverse JSF application - - >### Changes From the Style Guide - > - >The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide](https://guides.dataverse.org/en/latest/style/index.html), but the following changes have been made, especially for accessibility. - > - >#### Links - > - >We added an underline to links to make them accessible. - > - >#### File Labels - > - >Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies - the secondary color to the labels automatically, the color of the file label is now the global secondary color which is - a lighter shade of grey than what it used to be. - > - >We changed the citation block to be white with a colored border, to make the text in the box more accessible. - > - >### Changes in Functionality & Behavior - > - >Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during development we have found opportunities to review certain behaviors and apply changes where we find appropriate. - > - >#### Dataset Files Tab Search - > - >The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is searched in the database. - > - >The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search options are available for all versions in the same way, homogenizing behavior, although losing the possibility of using the Solr grammar. - > - >The decision of this change is made on the assumption that Solr may not be required in the context of files tab search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that the assumption is incorrect, we will work on extending the search capabilities to support Solr. +> ### Changes From the Style Guide +> +> The design system and frontend in this repo are inspired by the Dataverse Project [Style Guide][dv_docs_styleguide_url], +> but the following changes have been made, especially for accessibility. +> +> #### Links +> +> We added an underline to links to make them accessible. +> +> #### File Labels +> +> Now we are using Bootstrap with a theme, so there is only one definition for the secondary color. Since Bootstrap applies +> the secondary color to the labels automatically, the color of the file label is now the global secondary color which is +> a lighter shade of grey than what it used to be. +> +> We changed the citation block to be white with a colored border, to make the text in the box more accessible. +> +> ### Changes in Functionality & Behavior +> +> Our main goal is to replicate the behavior of the original JSF application in all its functionalities, although during +> development we have found opportunities to review certain behaviors and apply changes where we find appropriate. +> +> #### Dataset Files Tab Search +> +> The original Dataset JSF page uses Solr to search for files based on the available filters. Past dataset versions are +> not indexed in Solr, so the filter option is not available (hidden) for such versions. When a version is indexed, the +> search text is searched in Solr, and Solr grammar can be applied. When the version is not indexed, the search text is +> searched in the database. +> +> The new SPA does not use Solr as the API endpoint it uses performs all queries on the database. Filters and search +> options are available for all versions in the same way, homogenizing behavior, although losing the possibility of +> using the Solr grammar. +> +> The decision of this change is made on the assumption that Solr may not be required in the context of files tab +> search, whose search facets are reduced compared to other in-application searches. Therefore, if we find evidence that +> the assumption is incorrect, we will work on extending the search capabilities to support Solr.

    (back to top)

    - ## Getting Started _To get a local copy up and running follow these simple example steps._ @@ -207,31 +211,33 @@ _To get a local copy up and running follow these simple example steps._ 2. **Docker**: We use Docker Desktop, but the Docker CLI will also work. 3. **Create a Copy of .npmrc**: In the project directory root, duplicate `.npmrc.example`, saving the copy as `.npmrc`. - > ```bash - > # root project directory - > cp .npmrc.example .npmrc - > ``` + > ```bash + > # root project directory + > cp .npmrc.example .npmrc + > ``` -4. **Create and Add Your Npm and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps outlined below. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url]. +4. **Create and Add Your Npm and GitHub Tokens**: In order to connect with the Dataverse API, developers will need to + install [@iqss/dataverse-client-javascript][dv_repo_dvclientjs_npm_url] from the GitHub registry by following the steps + outlined below. Read more about access tokens on [GitHub Docs][dv_docs_github_userauthtoken_url]. - > **Getting a GitHub Token** - > 1. Go to your GitHub [Personal Access Tokens][dv_docs_github_token_url] settings - > 2. Select `Generate new token (classic)` - > 3. Give the token a name and select scope `read:packages` - > 4. Copy the generated token and replace the string `YOUR_GITHUB_AUTH_TOKEN` in the previously created `.npmrc` file. - > Now, you should be able to install the [Dataverse JavaScript][dv_repo_dvclientjs_url] client using npm. + > **Getting a GitHub Token** + > + > 1. Go to your GitHub [Personal Access Tokens][dv_docs_github_token_url] settings + > 2. Select `Generate new token (classic)` + > 3. Give the token a name and select scope `read:packages` + > 4. Copy the generated token and replace the string `YOUR_GITHUB_AUTH_TOKEN` in the previously created `.npmrc` file. + > Now, you should be able to install the [Dataverse JavaScript][dv_repo_dvclientjs_url] client using npm. Afterwards, your .npmrc file should resemble the following: ```properties - # .npmrc - legacy-peer-deps=true # js-dataverse registry //npm.pkg.github.com/:_authToken= @iqss:registry=https://npm.pkg.github.com/ ``` +
    ### Installation & Setup @@ -240,14 +246,15 @@ legacy-peer-deps=true ```bash # root project directory - npm install ``` + > [!WARNING] > You may see a message about vulnerabilities after running this command. > -> Please check this announcement from Create React App repository [facebook/create-react-app#11174][_uses_repo_cra_error_url]. These vulnerabilities will not be included in the production build since they come from libraries only used during development. - +> Please check this announcement from Create React App repository +> [facebook/create-react-app#11174][_uses_repo_cra_error_url]. These vulnerabilities will not be included in the +> production build since they come from libraries only used during development. 2. Build the UI Library, needed for running the application. @@ -256,20 +263,17 @@ npm install cd packages/design-system && npm run build ``` - - **Running & Building the App:** Run the app in the development mode. Open [http://localhost:5173][dv_app_localhost_build_url] to view it in your browser. ```bash # root project directory - npm start ``` -The application will actively watch the directory for changes and reload when changes are saved. You may also see any existing linting errors in the console. - +The application will actively watch the directory for changes and reload when changes are saved. You may also see any +existing linting errors in the console. ```bash # root project directory @@ -281,13 +285,16 @@ npm run build npm run preview ``` +
    **Storybook:** Runs the Storybook in the development mode. -There are 2 Storybook instances, one for the general Design System and one for the Dataverse Frontend component specifications. Both should be started automatically and available at: +There are 2 Storybook instances, one for the general Design System and one for the Dataverse Frontend component +specifications. Both should be started automatically and available at: + - Dataverse Frontend Storybook: [http://localhost:6006/][dv_app_localhost_storybook_url] - Dataverse Design System Storybook: [http://localhost:6007/][dv_app_localhost_designsystem_url] @@ -303,6 +310,7 @@ npm run build-storybook ``` Note that both Storybook instances are also published to Chromatic as part of the build and merge processes, located at: + - [DataverseFrontend-Chromatic](https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd) - [DataverseDesignSystem-Chromatic](https://www.chromatic.com/builds?appId=646fbe232a8d3b501a1943f3) @@ -325,44 +333,44 @@ npm run cy:open-e2e [cy:open-unit] npm run test:coverage ``` +
    Using `grep` with Cypress ->The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. -> ->Some examples used by the grep library are below for reference: +> The project includes [@cypress/grep][_uses_lib_grep_url] for running specific tests. > ->```bash -># root project directory +> Some examples used by the grep library are below for reference: > -># run only the tests with "auth user" in the title ->$ npx cypress run --env grep="auth user" +> ```bash +> # root project directory > -># run tests with "hello" or "auth user" in their titles by separating them with ";" character ->$ npx cypress run --env grep="hello; auth user" ->``` +> # run only the tests with "auth user" in the title +> $ npx cypress run --env grep="auth user" > ->To target specific tests, add `--spec` argument +> # run tests with "hello" or "auth user" in their titles by separating them with ";" character +> $ npx cypress run --env grep="hello; auth user" +> ``` > ->```bash -># root project directory +> To target specific tests, add `--spec` argument > ->$ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" ->\ --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx ->``` +> ```bash +> # root project directory > +> $ npx cypress run --env grep="loads the restricted files when the user is logged in as owner" +> \ --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +> ``` > ->**Repeat and burn tests** ->You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in the spec A five times using: +> **Repeat and burn tests** +> You can run the selected tests multiple times by using the `burn=N` parameter. For example, run all all the tests in +> the spec Five times using: > ->```bash -># root project directory -> ->$ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx ->``` +> ```bash +> # root project directory > +> $ npx cypress run --env burn=5 --spec tests/e2e-integration/e2e/sections/dataset/Dataset.spec.tsx +> ```
    @@ -385,8 +393,8 @@ npm run lint:fix Launch the prettier formatter. -We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at [vscode-settings][dv_repo_vscode_url] on GitHub. - +We recommend you to configure your IDE to run prettier on save. See the official IDE setups used by the IQSS team at +[vscode-settings][dv_repo_vscode_url] on GitHub. ```bash # root project directory @@ -400,11 +408,14 @@ npm run format A containerized environment, oriented to local development, is available to be run from the repository. -This environment contains a dockerized instance of the Dataverse backend with its dependent services (database, mailserver, etc), as well as an npm development server running the SPA frontend (With code watching). +This environment contains a dockerized instance of the Dataverse backend with its dependent services (database, +mail server, etc.), as well as a npm development server running the SPA frontend (With code watching). -This environment is intended for locally testing any functionality that requires access to the Dataverse API from the SPA frontend. +This environment is intended for locally testing any functionality that requires access to the Dataverse API from the +SPA frontend. -There is an Nginx reverse proxy container on top of the frontend and backend containers to avoid CORS issues while testing the application. +There is a Nginx reverse proxy container on top of the frontend and backend containers to avoid CORS issues while +testing the application.
    @@ -421,15 +432,21 @@ $ ./run-env.sh # Removes the project and its dependencies $ ./rm-env.sh ``` -Note that the image tag in the docker registry must to be pre pushed, otherwise the script will fail. You can find the existing tags on DockerHub [@gdcc/dataverse][dv_app_docker_image_url] -If you are running the script for the first time, it may take a while, since npm has to install all project dependencies. This can also happen if you added new dependencies to `package.json`, or used the _uninstall_ script to remove current project files and shut down any running containers. +Note that the image tag in the docker registry must be pre pushed, otherwise the script will fail. You can find the +existing tags on DockerHub [@gdcc/dataverse][dv_app_docker_image_url] + +If you are running the script for the first time, it may take a while, since npm has to install all project dependencies. +This can also happen if you added new dependencies to `package.json`, or used the _uninstall_ script to remove current +project files and shut down any running containers. Once the script has finished, you will be able to access Dataverse via: + - Dataverse SPA Frontend: [http://localhost:8000/spa][dv_app_localhost_spa_url] - Dataverse JSF Application: [http://localhost:8000][dv_app_localhost_legacy_url] -Note: The Dataverse configbaker takes some time to start the application, so the application will not be accessible until the bootstrapping is complete. +Note: The Dataverse configbaker takes some time to start the application, so the application will not be accessible until +the bootstrapping is complete.
    @@ -442,18 +459,22 @@ If you want to add test data (collections and datasets) to the Dataverse instanc $ ./add-env-data.sh ``` -Note: The above command uses the [dataverse-sample-data][dv_repo_dvsampledata_url] repository whose scripts occasionally fail, so some of the test data may not be added. -
    +Note: The above command uses the [dataverse-sample-data][dv_repo_dvsampledata_url] repository whose scripts occasionally +fail, so some test data may not be added. -### Deployment +
    -Once the site is built through the `npm run build` command, it can be deployed in different ways to different types of infrastructure, depending the needs of the installation. +## Deployment -We are working to provide different preconfigured automated deployment options, seeking to support common use cases today for installing applications of this nature. +Once the site is built through the `npm run build` command, it can be deployed in different ways to different types of +infrastructure, depending on the needs of the installation. -The current automated deployment options are available within the GitHub `deploy` workflow, which is designed to be run manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment. +We are working to provide different preconfigured automated deployment options, seeking to support common use cases +today for installing applications of this nature. +The current automated deployment options are available within the GitHub `deploy` workflow, which is designed to be run +manually from GitHub Actions. The deployment option is selected via a dropdown menu, as well as the target environment.
    Examples for AWS and Payara @@ -464,171 +485,132 @@ This option will build and deploy the application to a remote S3 bucket. For this workflow to work, a GitHub environment must be configured with the following environment secrets: - - `AWS_ACCESS_KEY_ID` - - `AWS_SECRET_ACCESS_KEY` - - `AWS_S3_BUCKET_NAME` - - `AWS_DEFAULT_REGION` +- `AWS_ACCESS_KEY_ID` +- `AWS_SECRET_ACCESS_KEY` +- `AWS_S3_BUCKET_NAME` +- `AWS_DEFAULT_REGION` -Note that for the deployment to the S3 bucket to succeed, you must make the following changes to the bucket via the S3 web interface (or equivalent changes using aws-cli or similar tools): +Note that for the deployment to the S3 bucket to succeed, you must make the following changes to the bucket via the S3 +web interface (or equivalent changes using aws-cli or similar tools): - - Under _`Permissions`_ ⏵ _`Permissions Overview`_ ⏵ _`Block public access (bucket settings)`_ ⏵ click _`Edit`_, then __uncheck__ _`Block all public access`_ and save. - - Under _`Properties`_ ⏵ _`Static website hosting`_ ⏵ click _`Edit`_ and enable it. Change _`Index document`_ and _`Error document`_ to `index.html`. - - Under _`Bucket Policy`_, click _`Edit`_ and paste the following policy (changing `` to your bucket name) and save. +- Under _`Permissions`_ ⏵ _`Permissions Overview`_ ⏵ _`Block public access (bucket settings)`_ ⏵ click _`Edit`_, then + **uncheck** _`Block all public access`_ and save. +- Under _`Properties`_ ⏵ _`Static website hosting`_ ⏵ click _`Edit`_ and enable it. Change _`Index document`_ and + _`Error document`_ to `index.html`. +- Under _`Bucket Policy`_, click _`Edit`_ and paste the following policy (changing `` to your bucket name) + and save. ```json { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "PublicReadGetObject", - "Principal": "*", - "Effect": "Allow", - "Action": [ - "s3:GetObject" - ], - "Resource": [ - "arn:aws:s3:::/*" - ] - } - ] + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "PublicReadGetObject", + "Principal": "*", + "Effect": "Allow", + "Action": ["s3:GetObject"], + "Resource": ["arn:aws:s3:::/*"] + } + ] } ``` -You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; `http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` +You should see the deployed app at `http://[BUCKET-NAME].s3-website-[REGION].amazonaws.com`, for example; +`http://my-dataverse-bucket.s3-website-us-east-1.amazonaws.com/` #### Deployment with Payara This option will build and deploy the application to a remote Payara server. -This option is intended for an "all-in-one" solution, where the Dataverse backend application and the frontend application run on the same Payara server. +This option is intended for an "all-in-one" solution, where the Dataverse backend application and the frontend +application run on the same Payara server. For this workflow to work, a GitHub environment must be configured with the following environment secrets: - - `PAYARA_INSTANCE_HOST` - - `PAYARA_INSTANCE_USERNAME` - - `PAYARA_INSTANCE_SSH_PRIVATE_KEY` +- `PAYARA_INSTANCE_HOST` +- `PAYARA_INSTANCE_USERNAME` +- `PAYARA_INSTANCE_SSH_PRIVATE_KEY` -It is important that the remote instance is correctly pre-configured, with the Payara server running, and a service account for Dataverse with the corresponding SSH key pair established. +It is important that the remote instance is correctly pre-configured, with the Payara server running, and a service +account for Dataverse with the corresponding SSH key pair established. -A base path for the frontend application can be established on the remote server by setting the corresponding field in the workflow inputs. This mechanism prevents conflicts between the frontend application and any pre-existing deployed application running on Payara, which can potentially be a Dataverse backend. This way, only the routes with the base path included will redirect to the frontend application. +A base path for the frontend application can be established on the remote server by setting the corresponding field in +the workflow inputs. This mechanism prevents conflicts between the frontend application and any pre-existing deployed +application running on Payara, which can potentially be a Dataverse backend. This way, only the routes with the base +path included will redirect to the frontend application.

    (back to top)


    - -## Usage - -Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. - -_For more examples, please refer to the [Documentation][dv_docs_devs_url]_ - - - - - -This project uses Atomic Design for it's Components. Here are several resources for Atomic Design if you are unfamiliar: - - - - - - -

    (back to top)

    -
    - ## Roadmap -Interested in what's being developed currently? See the [open issues][dv_repo_issues_url] for a full list of proposed features (and known issues), and what we are working on in the [currently planned sprint][dv_repo_sprint_url]. +Interested in what's being developed currently? See the [open issues][dv_repo_issues_url] for a full list of proposed +features (and known issues), and what we are working on in the [currently planned sprint][dv_repo_sprint_url]. -Keep an eye out on [The Institute for Quantitative Social Science (IQSS) Dataverse Roadmap][hvd_iqss_roadmap_url] at Harvard University to get a look at upcoming initiatives for the project. - - - +Keep an eye out on [The Institute for Quantitative Social Science (IQSS) Dataverse Roadmap][hvd_iqss_roadmap_url] at +Harvard University to get a look at upcoming initiatives for the project.

    (back to top)


    - - ## Contributing -We love PRs! Read the Contributor Guidelines for more info. Any contributions you make are **greatly appreciated**. - -If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the `enhancement` tag. - -Got Questions? Join the conversation on [Zulip][dv_community_zulip_url], or our Google Groups for [Developers][dv_community_google_devs_url] and [Users][dv_community_google_users_url]. Or attend community meetings, hosted by the The Global Dataverse Community Consortium to collaborate with the interest groups for [Frontend Development][dv_community_gdcc_ui_url] and [Containerization][dv_community_gdcc_containers_url], learn and share with communities around the world! +We love PRs! Read the [Contributor Guidelines](CONTRIBUTING) for more info. Any contributions you make are **greatly appreciated**. - -Find videos and release overviews on our YouTube Channel, and check out the resources on our [website][dv_docs_dataverse_url]. +Got Questions? Join the conversation on [Zulip][dv_community_zulip_url], or our Google Groups for +[Developers][dv_community_google_devs_url] and [Users][dv_community_google_users_url]. Or attend community meetings, +hosted by the Global Dataverse Community Consortium to collaborate with the interest groups for +[Frontend Development][dv_community_gdcc_ui_url] and [Containerization][dv_community_gdcc_containers_url], +learn and share with communities around the world!

    (back to top)


    - - - - -## Contact - -Email us with software installation questions. Please note our response time is generally 24 business hours. - - - - -### For Developers and Dataverse Repositories - -**Report issues and contribute to our code**: - -Report bugs and add feature requests in GitHub Issues or use GitHub pull requests, if you have some code, scripts or documentation that you'd like to share. If you have a security issue to report, please email security@dataverse.org. - -Ask a question or start a discussion: A great place to publicly share feedback, ideas, feature requests, and troubleshoot any issues is in the dataverse-community mailing list. Additional mailing lists are available, including language-specific ones. - - - -

    (back to top)

    -
    - - ## Acknowledgments Chromatic -Thanks to [Chromatic][_uses_chromatic_url] for providing the visual testing platform that helps us review UI changes and catch visual regressions. +Thanks to [Chromatic][_uses_chromatic_url] for providing the visual testing platform that helps us review UI changes +and catch visual regressions.

    (back to top)


    -*** +--- ### Built With -This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples. +- [![ReactJS][_shield_reactjs]][_uses_reactjs_url] +- [![NodeJS][_shield_nodejs]][_uses_nodejs_url] +- [![TypeScript][_shield_typescript]][_uses_typescript_url] +- [![Bootstrap][_shield_bootstrap]][_uses_bootstrap_url] +- [![Cypress][_shield_cypress]][_uses_cypress_url] +- [![TestingLibrary][_shield_testinglibrary]][_uses_testinglibrary_url] +- [![Storybook][_shield_storybook]][_uses_storybook_url] +- [![AmazonS3][_shield_amazons3]][_uses_aws3_url] +- [![Docker][_shield_docker]][_uses_docker_url]

    (back to top)


    -*** +--- ## License -Distributed under the Apache License, Version 2.0. See `LICENSE` for more information. +Distributed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for more information.

    (back to top)


    - - + [dv_repo_url]: https://github.com/IQSS/dataverse-frontend [dv_repo_issues_url]: https://github.com/IQSS/dataverse-frontend/issues [dv_repo_sprint_url]: https://github.com/orgs/IQSS/projects/34/views/23 @@ -643,6 +625,7 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [dv_repo_dvclientjs_url]: https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript [dv_repo_dvclientjs_npm_url]: https://www.npmjs.com/package/js-dataverse [dv_repo_dvsampledata_url]: https://github.com/IQSS/dataverse-sample-data @@ -653,6 +636,7 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [dv_app_beta_spa_url]: https://beta.dataverse.org/spa [dv_app_beta_legacyjsf_url]: https://beta.dataverse.org [dv_app_legacyjsf_demo_url]: https://demo.dataverse.org/ @@ -661,26 +645,31 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform [dv_app_localhost_designsystem_url]: http://localhost:6007/ [dv_app_localhost_spa_url]: http://localhost:8000/spa [dv_app_localhost_legacy_url]: http://localhost:8000/ + + [dv_app_docker_image_url]: https://hub.docker.com/r/gdcc/dataverse/tags + [dv_community_gdcc_url]: https://www.gdcc.io/ [dv_community_gdcc_ui_url]: https://ui.gdcc.io/ [dv_community_gdcc_containers_url]: https://ct.gdcc.io/ [dv_community_google_devs_url]: https://groups.google.com/g/dataverse-dev [dv_community_google_users_url]: https://groups.google.com/g/dataverse-community -[dv_community_zulip_url]: https://dataverse.zulipchat.com/ +[dv_community_zulip_url]: https://dataverse.zulipchat.com/#narrow/stream/410361-ui-dev + [hvd_iqss_url]: https://www.iq.harvard.edu/ [hvd_iqss_roadmap_url]: https://www.iq.harvard.edu/roadmap-dataverse-project [hvd_legacyjsf_url]: https://dataverse.harvard.edu/ + [dv_docs_dataverse_url]: https://dataverse.org/ [dv_docs_about_url]: https://dataverse.org/about [dv_docs_styleguide_url]: https://guides.dataverse.org/en/latest/style/index.html @@ -691,6 +680,7 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [_uses_reactjs_url]: https://reactjs.org/ [_uses_nodejs_url]: https://nodejs.org/ [_uses_typescript_url]: https://typescriptlang.org/ @@ -704,12 +694,16 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform [_uses_chromatic_url]: https://www.chromatic.com/ [_uses_repo_cra_error_url]: https://github.com/facebook/create-react-app/issues/11174 [_uses_tool_chromatic_url]: https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd + + [_uses_lib_grep_url]: https://www.npmjs.com/package/@cypress/grep + + [_shield_reactjs]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB [_shield_nodejs]: https://img.shields.io/badge/node.js-000000?style=for-the-badge&logo=nodedotjs&logoColor=white [_shield_typescript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white @@ -722,12 +716,16 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform [_shield_zulip]: https://img.shields.io/badge/zulip-chat?style=for-the-badge&logo=zulip&logoColor=%236492FE [_shield_googledevs]: https://img.shields.io/badge/Developer_Group-white?style=for-the-badge&logo=google [_shield_googleusers]: https://img.shields.io/badge/User_Group-white?style=for-the-badge&logo=google + + [_shield_projectstatus]: https://img.shields.io/badge/repo_status-WIP-yellow?style=for-the-badge [_shield_contributors]: https://img.shields.io/github/contributors/IQSS/dataverse-frontend?branch=develop&style=for-the-badge [_shield_stargazers]: https://img.shields.io/github/stars/iqss/dataverse-frontend?style=for-the-badge [_shield_coveralls]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge + + [_shield_workflow]: https://img.shields.io/github/actions/workflow/status/IQSS/dataverse-frontend/test.yml?branch=develop&style=for-the-badge [_shield_issues]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge [_shield_forks]: https://img.shields.io/github/forks/IQSS/dataverse-frontend?style=for-the-badge @@ -735,18 +733,24 @@ Distributed under the Apache License, Version 2.0. See `LICENSE` for more inform + [_img_dv_logo_withbackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6986476f-39ba-46a4-9be0-f05cd8e92244 [_img_dv_logo_nobackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6c4d79e4-7be5-4102-88bd-dfa167dc79d3 [_img_screenshot]: images/screenshot.png + [_video_demo_datasetpage_url]: https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ + + [_video_demo_filetable_url]: https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ + [_social_twitter]: https://twitter.com/your_username + From 6916a3493f2e205db0086e57d33d04e90983ad1d Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 11:52:48 +0200 Subject: [PATCH 17/26] feat(Frontend Guides): update issues templates --- .github/ISSUE_TEMPLATE/bug_report.md | 41 ++++++++++++++++++----- .github/ISSUE_TEMPLATE/feature_request.md | 31 +++++++++++++---- .github/PULL_REQUEST_TEMPLATE.md | 16 ++++----- .github/SUPPORT.md | 10 ------ 4 files changed, 64 insertions(+), 34 deletions(-) delete mode 100644 .github/SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index cf668e2fe..bd34df011 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,23 +1,46 @@ -# What steps does it take to reproduce the issue? +--- +name: Bug report +about: Did you encounter something unexpected or incorrect in the Dataverse software? +We'd like to hear about it! +title: '' +labels: 'Type: Bug' +assignees: '' -## When does this issue occur? +--- -## Which section(s) does it occurs on? + -## Which version of Dataverse Frontend are you using? +**What steps does it take to reproduce the issue?** -## Any related open or closed issues to this bug report? +- When does this issue occur? -# Screenshots: +- Which page(s) does it occur on? + +- What happens? + +- To whom does it occur (all users, curators, superusers)? + +- What did you expect to happen? + +**Which version of Dataverse Frontend are you using?** + +**Any related open or closed issues to this bug report?** + +**Screenshots:** No matter the issue, screenshots are always welcome. To add a screenshot, please use one of the following formats and/or methods described here: - https://help.github.com/en/articles/file-attachments-on-issues-and-pull-requests +- diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 8c62e03b4..e1fa50e35 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,13 +1,30 @@ -## Overview of the Feature Request +--- +name: Feature request +about: Suggest an idea or new feature for the Dataverse software! +title: 'Feature Request/Idea:' +labels: 'Type: Feature' +assignees: '' +--- -## What kind of user is the feature intended for? + -## What existing behavior do you want changed? +**Overview of the Feature Request** -## Any brand new behavior do you want to add to Dataverse? +**What kind of user is the feature intended for?** +(Example users roles: API User, Curator, Depositor, Guest, Superuser, Sysadmin) -## Any open or closed issues related to this feature request? +**What inspired the request?** + +**What existing behavior do you want changed?** + +**Any brand-new behavior do you want to add to Dataverse?** + +**Any open or closed issues related to this feature request?** diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fbfad5f96..b57aa23fc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,15 @@ -## What this PR does / why we need it: +**What this PR does / why we need it**: -## Which issue(s) this PR closes: +**Which issue(s) this PR closes**: -- Closes # +Closes # -## Special notes for your reviewer: +**Special notes for your reviewer**: -## Suggestions on how to test this: +**Suggestions on how to test this**: -## Does this PR introduce a user interface change? If mockups are available, please link/include them here: +**Does this PR introduce a user interface change? If mockups are available, please link/include them here**: -## Is there a release notes update needed for this change?: +**Is there a release notes update needed for this change?**: -## Additional documentation: \ No newline at end of file +**Additional documentation**: diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md deleted file mode 100644 index 8d74d941f..000000000 --- a/.github/SUPPORT.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Looking for support? We want to help - -Please post your question to X (#) using the Timber tag. - -## Other places - -You can use [GitHub Discussions](#) to open up questions and engage in discussions with the contributors and other users. - -Please don't post to the [EXAMPLE forum](#). You might see a response, but it will just redirect you to either GitHub (for bugs/issues) or StackOverflow (for usage/support questions). From 6831b7c6d65d12467fc0d967c169cb4e800d30c2 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 11:59:24 +0200 Subject: [PATCH 18/26] feat(Frontend Guides): remove AUTHORS.md --- .storybook/main.ts | 14 +++++++------- AUTHORS.md | 22 ---------------------- CODE_OF_CONDUCT.md | 22 +++++++++++----------- 3 files changed, 18 insertions(+), 40 deletions(-) delete mode 100644 AUTHORS.md diff --git a/.storybook/main.ts b/.storybook/main.ts index f7066d01f..e0c6acb07 100644 --- a/.storybook/main.ts +++ b/.storybook/main.ts @@ -1,16 +1,16 @@ -import { dirname, join } from "path"; +import { dirname, join } from 'path' import type { StorybookConfig } from '@storybook/react-vite' const config: StorybookConfig = { stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'], addons: [ - getAbsolutePath("@storybook/addon-links"), - getAbsolutePath("@storybook/addon-essentials"), - getAbsolutePath("@storybook/addon-interactions"), - getAbsolutePath("@storybook/addon-a11y") + getAbsolutePath('@storybook/addon-links'), + getAbsolutePath('@storybook/addon-essentials'), + getAbsolutePath('@storybook/addon-interactions'), + getAbsolutePath('@storybook/addon-a11y') ], framework: { - name: getAbsolutePath("@storybook/react-vite"), + name: getAbsolutePath('@storybook/react-vite'), options: {} }, docs: { @@ -21,5 +21,5 @@ const config: StorybookConfig = { export default config function getAbsolutePath(value: string): any { - return dirname(require.resolve(join(value, "package.json"))); + return dirname(require.resolve(join(value, 'package.json'))) } diff --git a/AUTHORS.md b/AUTHORS.md deleted file mode 100644 index 9708d6a30..000000000 --- a/AUTHORS.md +++ /dev/null @@ -1,22 +0,0 @@ -# Below is a list of people and organizations that have contributed - -# to the Dataverse Frontend project. Names should be added to the list like so: - -# - -# Name/Organization - -# - -# Anyone who has contributed to the Dataverse Frontend project in any way (not - -# limited to submitting PRs) is welcome to submit a PR to add their - -# name to this file. - -# - -# Thanks to everyone for your contributions! - -Harvard University IQSS Team -FirstName LastName diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 70a654f0e..0240e7aa8 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -14,21 +14,21 @@ appearance, race, religion, or sexual identity and orientation. 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 +- 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 +- 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 +- 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 +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities @@ -73,4 +73,4 @@ available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.ht [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see -https://www.contributor-covenant.org/faq \ No newline at end of file +https://www.contributor-covenant.org/faq From aeece97563678aa3ae34dc7011c569be36ae3e9e Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 15:24:18 +0200 Subject: [PATCH 19/26] feat(Frontend Guides): remove empty CHANGELOG --- CHANGELOG.md | 33 --------------------------------- 1 file changed, 33 deletions(-) delete mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 99d2ef963..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,33 +0,0 @@ -# Change Log - -Resources for generating a changelog: - -[skywinder/Github-Changelog-Generator](https://github.com/skywinder/Github-Changelog-Generator) - generates a full changelog that overwrites the existing CHANGELOG.md. - -[hzalaz/wt-oss-milestone-changelog](https://github.com/hzalaz/wt-oss-milestone-changelog) - generates a snippet of Markdown that can be added to a CHANGELOG.md. - -[conventional-changelog/conventional-changelog](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli) - generates a full changelog based on commit history with the option to append to an existing changelog. - - - -All notable changes to this project will be documented in this file. -We follow the [Semantic Versioning 2.0.0](http://semver.org/) format. - -## x.y.z - YYYY-MM-DD - -### Added - -- Lorem ipsum dolor sit amet - -### Deprecated - -- Nothing. - -### Removed - -- Nothing. - -### Fixed - -- Nothing. -- From 60b6af2a37def8c94d10b6d58018190937473ca6 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 16:24:41 +0200 Subject: [PATCH 20/26] feat(Developer Guide): add note about .npmrc.example --- DEVELOPER_GUIDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index eb3e6f425..c2aa13c9e 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -68,6 +68,10 @@ legacy-peer-deps=true @iqss:registry=https://npm.pkg.github.com/ ``` +> **Note:** The .npmrc file is not identical to .npmrc.example, as the latter contains the registry to publish the design +> system, see [Publishing the Design System](#publishing-the-design-system) for more information. To run the project you only +> need the above configuration. +

    (back to top)


    From c54082afd1611abb85908edaa2fe860da91f3a75 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 16:31:44 +0200 Subject: [PATCH 21/26] feat(Developer Guide): remove unused links --- DEVELOPER_GUIDE.md | 102 --------------------------------------------- README.md | 5 --- 2 files changed, 107 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index c2aa13c9e..cba4a3c7e 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -819,39 +819,16 @@ The Design System is published to the npm Package Registry. To publish a new ver - - - - -[dv_repo_url]: https://github.com/IQSS/dataverse-frontend -[dv_repo_issues_url]: https://github.com/IQSS/dataverse-frontend/issues -[dv_repo_sprint_url]: https://github.com/orgs/IQSS/projects/34/views/23 -[dv_repo_contributors_url]: https://github.com/IQSS/dataverse-frontend/graphs/contributors -[dv_repo_stargazers_url]: https://github.com/IQSS/dataverse-frontend/stargazers -[dv_repo_coveralls_url]: https://coveralls.io/github/IQSS/dataverse-frontend?branch=develop -[dv_repo_workflow_url]: https://github.com/IQSS/dataverse-frontend/actions -[dv_repo_forks_url]: https://github.com/IQSS/dataverse-frontend/forks -[dv_repo_tag_url]: https://github.com/IQSS/dataverse-frontend/tags -[dv_repo_projectstatus_url]: https://www.repostatus.org/#wip -[dv_repo_releases_url]: https://github.com/IQSS/dataverse-frontend/releases - [dv_repo_dvclientjs_url]: https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript [dv_repo_dvclientjs_npm_url]: https://www.npmjs.com/package/js-dataverse [dv_repo_dvsampledata_url]: https://github.com/IQSS/dataverse-sample-data -[dv_repo_legacyjsf_url]: https://github.com/IQSS/dataverse/ -[dv_repo_legacyjsf_releases_url]: https://github.com/IQSS/dataverse/releases -[dv_repo_legacyjsf_issues_url]: https://github.com/IQSS/dataverse/issues -[dv_repo_vscode_url]: https://github.com/IQSS/vscode-settings -[dv_app_beta_spa_url]: https://beta.dataverse.org/spa -[dv_app_beta_legacyjsf_url]: https://beta.dataverse.org -[dv_app_legacyjsf_demo_url]: https://demo.dataverse.org/ [dv_app_localhost_build_url]: http://localhost:5173 [dv_app_localhost_storybook_url]: http://localhost:6006/ [dv_app_localhost_designsystem_url]: http://localhost:6007/ @@ -862,50 +839,17 @@ The Design System is published to the npm Package Registry. To publish a new ver [dv_app_docker_image_url]: https://hub.docker.com/r/gdcc/dataverse/tags - - - -[dv_community_gdcc_url]: https://www.gdcc.io/ -[dv_community_gdcc_ui_url]: https://ui.gdcc.io/ -[dv_community_gdcc_containers_url]: https://ct.gdcc.io/ -[dv_community_google_devs_url]: https://groups.google.com/g/dataverse-dev -[dv_community_google_users_url]: https://groups.google.com/g/dataverse-community -[dv_community_zulip_url]: https://dataverse.zulipchat.com/#narrow/stream/410361-ui-dev - - - - -[hvd_iqss_url]: https://www.iq.harvard.edu/ -[hvd_iqss_roadmap_url]: https://www.iq.harvard.edu/roadmap-dataverse-project -[hvd_legacyjsf_url]: https://dataverse.harvard.edu/ - -[dv_docs_dataverse_url]: https://dataverse.org/ -[dv_docs_about_url]: https://dataverse.org/about -[dv_docs_styleguide_url]: https://guides.dataverse.org/en/latest/style/index.html -[dv_docs_api_url]: http://guides.dataverse.org/en/latest/api/index.html -[dv_docs_devs_url]: https://guides.dataverse.org/en/latest/developers/index.html [dv_docs_github_userauthtoken_url]: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app [dv_docs_github_token_url]: https://github.com/settings/tokens -[_uses_reactjs_url]: https://reactjs.org/ -[_uses_nodejs_url]: https://nodejs.org/ -[_uses_typescript_url]: https://typescriptlang.org/ -[_uses_bootstrap_url]: https://getbootstrap.com -[_uses_cypress_url]: https://cypress.io/ -[_uses_testinglibrary_url]: https://testing-library.com/docs/react-testing-library/intro/ -[_uses_storybook_url]: https://storybook.js.org/ -[_uses_payara_url]: https://www.payara.fish/ [_uses_docker_url]: https://www.docker.com/products/docker-desktop/ -[_uses_aws3_url]: https://aws.amazon.com/ -[_uses_chromatic_url]: https://www.chromatic.com/ [_uses_repo_cra_error_url]: https://github.com/facebook/create-react-app/issues/11174 -[_uses_tool_chromatic_url]: https://www.chromatic.com/builds?appId=646f68aa9beb01b35c599acd @@ -916,53 +860,7 @@ The Design System is published to the npm Package Registry. To publish a new ver -[_shield_reactjs]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB -[_shield_nodejs]: https://img.shields.io/badge/node.js-000000?style=for-the-badge&logo=nodedotjs&logoColor=white -[_shield_typescript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white -[_shield_bootstrap]: https://img.shields.io/badge/Bootstrap-563D7C?style=for-the-badge&logo=bootstrap&logoColor=white -[_shield_cypress]: https://img.shields.io/badge/Cypress-69D3A7?style=for-the-badge&logo=cypress&logoColor=black -[_shield_testinglibrary]: https://img.shields.io/badge/TestingLibrary-E33332?style=for-the-badge&logo=testinglibrary&logoColor=white -[_shield_storybook]: https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white [_shield_docker]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white -[_shield_amazons3]: https://img.shields.io/badge/AmazonS3-569A31?style=for-the-badge&logo=amazons3&logoColor=white -[_shield_zulip]: https://img.shields.io/badge/zulip-chat?style=for-the-badge&logo=zulip&logoColor=%236492FE -[_shield_googledevs]: https://img.shields.io/badge/Developer_Group-white?style=for-the-badge&logo=google -[_shield_googleusers]: https://img.shields.io/badge/User_Group-white?style=for-the-badge&logo=google - - - -[_shield_projectstatus]: https://img.shields.io/badge/repo_status-WIP-yellow?style=for-the-badge -[_shield_contributors]: https://img.shields.io/github/contributors/IQSS/dataverse-frontend?branch=develop&style=for-the-badge -[_shield_stargazers]: https://img.shields.io/github/stars/iqss/dataverse-frontend?style=for-the-badge -[_shield_coveralls]: https://img.shields.io/coverallsCoverage/github/IQSS/dataverse-frontend?branch=develop&style=for-the-badge - - - -[_shield_workflow]: https://img.shields.io/github/actions/workflow/status/IQSS/dataverse-frontend/test.yml?branch=develop&style=for-the-badge -[_shield_issues]: https://img.shields.io/github/issues/IQSS/dataverse-frontend?style=for-the-badge -[_shield_forks]: https://img.shields.io/github/forks/IQSS/dataverse-frontend?style=for-the-badge -[_shield_tag]: https://img.shields.io/github/v/tag/iqss/dataverse-frontend?style=for-the-badge - - - - -[_img_dv_logo_withbackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6986476f-39ba-46a4-9be0-f05cd8e92244 -[_img_dv_logo_nobackground]: https://github.com/IQSS/dataverse-frontend/assets/7512607/6c4d79e4-7be5-4102-88bd-dfa167dc79d3 -[_img_screenshot]: images/screenshot.png - - - - -[_video_demo_datasetpage_url]: https://groups.google.com/g/dataverse-community/c/cxZ3Bal_-uo/m/h3kh3iVNCwAJ - - - -[_video_demo_filetable_url]: https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ - - - - -[_social_twitter]: https://twitter.com/your_username diff --git a/README.md b/README.md index 1aca36c1d..e34b60aa6 100644 --- a/README.md +++ b/README.md @@ -414,10 +414,5 @@ Distributed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for mo [_video_demo_filetable_url]: https://groups.google.com/g/dataverse-community/c/w_rEMddESYc/m/6F7QC1p-AgAJ - - - -[_social_twitter]: https://twitter.com/your_username - From 07fb7615854822999133b20f5f678dadeda7f96c Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 1 Apr 2024 17:14:04 +0200 Subject: [PATCH 22/26] feat(Frontend Guides): fix .github files to create issues --- CODE_OF_CONDUCT.md => .github/CODE_OF_CONDUCT.md | 0 CONTRIBUTING.md => .github/CONTRIBUTING.md | 0 .github/ISSUE_TEMPLATE/bug_report.md | 10 ++++------ README.md | 2 +- 4 files changed, 5 insertions(+), 7 deletions(-) rename CODE_OF_CONDUCT.md => .github/CODE_OF_CONDUCT.md (100%) rename CONTRIBUTING.md => .github/CONTRIBUTING.md (100%) diff --git a/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md similarity index 100% rename from CODE_OF_CONDUCT.md rename to .github/CODE_OF_CONDUCT.md diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to .github/CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index bd34df011..999e90fbe 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,20 +1,19 @@ --- name: Bug report -about: Did you encounter something unexpected or incorrect in the Dataverse software? -We'd like to hear about it! +about: Did you encounter something unexpected or incorrect in the Dataverse Frontend? + We'd like to hear about it! title: '' labels: 'Type: Bug' assignees: '' - --- From 8824d90d28f3c597b33fd874faaf1f33c021ad6e Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 16 Apr 2024 12:03:09 +0200 Subject: [PATCH 24/26] feat(Frontend Guides): add GitHub container registry link --- DEVELOPER_GUIDE.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index b2ce5f242..415a64f50 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -181,8 +181,11 @@ $ ./run-env.sh $ ./rm-env.sh ``` -Note that the image tag in the docker registry must be pre pushed, otherwise the script will fail. You can find the -existing tags on DockerHub [@gdcc/dataverse][dv_app_docker_image_url] +Please note that the image tag must be pre-pushed to the Docker registry; otherwise, the script will fail. You can find +the existing tags for alpha and unstable versions on DockerHub at [@gdcc/dataverse][dv_app_docker_image_url]. Images +associated with pull requests (PRs) are available in the [GitHub Container Registry]. + +````bash If you are running the script for the first time, it may take a while, since npm has to install all project dependencies. This can also happen if you added new dependencies to `package.json`, or used the _uninstall_ script to remove current @@ -206,7 +209,7 @@ If you want to add test data (collections and datasets) to the Dataverse instanc # /dev-env/ directory $ ./add-env-data.sh -``` +```` > Note: The above command uses the [dataverse-sample-data][dv_repo_dvsampledata_url] repository whose scripts occasionally > fail, so some test data may not be added. @@ -838,6 +841,7 @@ The Design System is published to the npm Package Registry. To publish a new ver [dv_app_docker_image_url]: https://hub.docker.com/r/gdcc/dataverse/tags +[Github Container Registry]: https://github.com/orgs/gdcc/packages/container/package/dataverse From abbb1379486f57cd0efda69bff881d0c4f924b3a Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 16 Apr 2024 12:07:24 +0200 Subject: [PATCH 25/26] feat(Fronted Guides): link e2e new issue to address the failures --- DEVELOPER_GUIDE.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 415a64f50..3e121292b 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -516,13 +516,11 @@ describe('Create Dataset', () => {
    -> **Note:** The current e2e tests are failing due to the following reasons: +> **Note:** Some end-to-end (e2e) tests are failing in local development environments despite passing in GitHub Actions. +> This discrepancy appears to be due to variations in machine resources. > -> - **Dataset JSDataverse Repository -> gets the total dataset count**: Calling `destroyAll()` before the "gets the total -> - dataset count" test in `DatasetJSDataverseRepository.spec.ts` causes an optimistic lock exception in Dataverse. -> -> **Solution:** We need to either reset the database after each test or find an alternative method to avoid the optimistic -> lock exception. Check the issue [here](https://github.com/IQSS/dataverse-frontend/issues/294). +> We need to investigate and potentially optimize several aspects of our local setup. Check the issue +> [here](https://github.com/IQSS/dataverse-frontend/issues/371). ### Patterns and Conventions From a3fa006721d14539c80eebe88744261259bf9884 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Wed, 17 Apr 2024 09:20:15 +0200 Subject: [PATCH 26/26] fix: merge conflict arrows --- README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/README.md b/README.md index dfe7ceab4..8e2740317 100644 --- a/README.md +++ b/README.md @@ -218,15 +218,8 @@ features (and known issues), and what we are working on in the [currently planne Keep an eye out on [The Institute for Quantitative Social Science (IQSS) Dataverse Roadmap][hvd_iqss_roadmap_url] at Harvard University to get a look at upcoming initiatives for the project. -<<<<<<< HEAD -

    (back to top)


    -======= -We have introduced an update to the breadcrumb navigation UI. Unlike in the original JSF application, where breadcrumbs -did not reflect the user's current location within the site, our new SPA design now includes this feature in the breadcrumbs. -Additionally, we have aligned with best practices by positioning all breadcrumbs at the top, before anything else in the UI. ->>>>>>> 3aa4685da974fdc9328c44866237bd8173e31cda ## Contributing