Merge pull request #118 from IQSS/113-documentation-v2

New documentation for js-dataverse v2

CONTRIBUTING.md

@@ -3,31 +3,39 @@
 First of all thank you very much for your interest in contributing to this project!
 
 ## Getting started
-1. Make sure that you have installed the project dependencies
-2. Build the project as explained in [README.md](README.md)
-3. Fork the repository
-4. Apply changes in your own branch
-5. Create a pull request that we will review
-6. Update README.md if necessary
+
+1. Fork the repository and clone your fork locally
+2. Follow the [Local Development](./docs/localDevelopment.md) guide for setting up your local development environment
+3. Create a branch and apply the desired changes on it
+4. Create a pull request from your fork branch targeting the develop branch of the root repository
 
 ## Checklist before creating PR
+
 - Project builds
 - Lint and format checks pass
-- Unit tests pass
-- Unit tests for new functionality/fix are added
+- Unit and integration tests pass
+- Unit and integration tests for new functionality/fix are added
+- Documentation is updated (Any new use case added or modified should be documented in the [Use Cases](./docs/useCases.md) section)
 
 ## Code of Conduct
+
 We abide by the upstream Code of Conduct at https://github.com/IQSS/dataverse/blob/develop/CODE_OF_CONDUCT.md and in addition ask the following.
 
 ### Git
+
 - Branch names are self descriptive
 - Commit messages are short and concise
 - Branch is put up to date before creating PR
 
 ### Our responsibilities
+
 - To keep the code clean
 - To provide constructive feedback to other developers
 - To maintain readable code at all times
 
 ## Getting help
-Please feel free to reach out in https://chat.dataverse.org or https://groups.google.com/g/dataverse-dev
+
+Please, do not hesitate to contact us through:
+
+- Zulip: https://dataverse.zulipchat.com/#narrow/stream/410361-ui-dev
+- Google Group: https://groups.google.com/g/dataverse-dev

README.md

@@ -1,85 +1,11 @@
-# dataverse-client-javascript
+# js-dataverse
 
 [![npm](https://img.shields.io/npm/v/js-dataverse.svg)](https://www.npmjs.com/package/js-dataverse)
 
 A JavaScript/TypeScript API wrapper for [Dataverse](http://guides.dataverse.org/en/latest/api/).
 
-## NPM
-
-A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse
-
-An unstable 2.x version of this package with breaking changes is under development. Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript
-
-## Getting Started
-
-This package is built using `node v19`, so it is recommended to use that version.
-
-Make sure that you install all the project dependencies:
-
-`npm install`
-
-## Build project
-
-In order to build the project, we need to run the following command:
-
-`npm run build`
-
-the build generated will be placed in `dist` folder.
-
-## Tests
-
-### Run all tests
-
-`npm run test`
-
-### Run unit tests
-
-`npm run test:unit`
-
-### Run integration tests
-
-`npm run test:integration`
-
-#### Configure the integration testing environment
-
-The integration testing environment is implemented with Test Containers and Docker Compose. The environment uses different environment variables, defined in a .env file, available in the _test/integration/environment_ folder.
-
-These environment variables can be updated as needed for integration testing. For example, we can specify the Dataverse image registry and tag, to point to the particular Dataverse image to test.
-
-- To test images generated in Dataverse PRs: Set `ghcr.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and the source branch name of a particular PR as the image tag (DATAVERSE_IMAGE_TAG).
-
-- To test the Dataverse develop branch: Set `docker.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and `unstable` as the image tag (DATAVERSE_IMAGE_TAG).
-
-### Run test coverage
-
-`npm run test:coverage`
-
-## Format and lint
-
-### Run formatter
-
-`npm run format`
-
-### Run linter
-
-Running a linting check on the code:
-
-`npm run lint`
-
-Fix linting checks on the code:
-
-`npm run lint:fix`
-
-## Publishing new version
-
-Automated publishing of versions could be automated when merging to master. Below are the steps that would be required to publish a new version:
-
-1. Run tests and checks
-2. Build the project
-3. Commit changes
-4. Upgrade npm version
-5. Publish, `npm publish`
-
-## Contributing
-
-We love contributors! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+- [Installation](./docs/installation.md)
+- [Use Cases](./docs/useCases.md)
+- [Local Development](./docs/localDevelopment.md)
+- [Contributing](./CONTRIBUTING.md)
+- [License](./LICENSE)

docs/installation.md

@@ -0,0 +1,108 @@
+# Installation
+
+Recommended versions node >=16 and npm >=8.
+
+## Getting Started with the Stable Version
+
+A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse
+
+Install the package stable version using npm:
+
+```bash
+npm install js-dataverse
+```
+
+## Getting Started with the Development Version
+
+An unstable 2.x version of this package with breaking changes is under development.
+
+Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript
+
+
+### Create a `.npmrc` file and add a token
+
+To install the [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript)
+from the GitHub registry, follow these steps to create an `.npmrc` file in the root of your project using your GitHub token.
+
+1. **Create `.npmrc`** in your project's root directory.
+
+   ```bash
+   touch .npmrc
+   ```
+
+2. **Replace the Token**
+
+   Open the newly created `.npmrc` file and replace `YOUR_GITHUB_TOKEN` with your actual GitHub token.
+
+   ```plaintext
+   legacy-peer-deps=true
+
+    //npm.pkg.github.com/:_authToken=<YOUR_GITHUB_AUTH_TOKEN>
+    @iqss:registry=https://npm.pkg.github.com/
+   ```
+
+#### How to Get a GitHub Token
+
+If you don't have a GitHub token yet, follow these steps:
+
+1. Go to your GitHub account settings.
+
+2. Navigate to "Developer settings" -> "Personal access tokens."
+
+3. Click "Personal access tokens" -> "Tokens (classic)" -> "Generate new token (classic)".
+
+4. Give the token a name and select the "read:packages" scope.
+
+5. Copy the generated token.
+
+6. Replace `YOUR_GITHUB_AUTH_TOKEN` in the `.npmrc` file with the copied token.
+
+Now, you should be able to install the Dataverse JavaScript client using npm.
+
+### Install the package
+
+Install the package development version using npm:
+
+```bash
+npm install @iqss/dataverse-client-javascript
+```
+
+## Initialization
+
+In order for the package to connect to the Dataverse API, there is an `APIConfig` object that should be initialized to set the preferred authentication mechanism with the associated credentials for connecting to the Dataverse API.
+
+Currently, the supported authentication mechanisms are:
+
+- **API Key**: The recommended authentication mechanism. The API Key should correspond to a particular Dataverse user account.
+
+- **Session Cookie**: This is an experimental feature primarily designed for Dataverse SPA development. To use this mechanism, you must enable the corresponding feature flag in the Dataverse installation (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism and instead use API Key authentication.
+
+It is recommended to globally initialize the `ApiConfig` object from the consuming application, as the configuration will be read on every API call made by the package's use cases.
+
+For example, in a React application, we can globally initialize the `ApiConfig` object in the `App` file, like this:
+
+```typescript
+ApiConfig.init(<DATAVERSE_API_BASE_URL>, DataverseApiAuthMechanism.API_KEY, <DATAVERSE_API_KEY>)
+
+function App() {
+  /* Yor App code */
+}
+
+export default App
+````
+
+The same example but with example values set:
+
+```typescript
+ApiConfig.init('http://localhost:8000/api/v1', DataverseApiAuthMechanism.API_KEY, 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
+
+function App() {
+  /* Yor App code */
+}
+
+export default App
+````
+
+We can initialize the `ApiConfig` object as an unauthenticated user, by setting `undefined` as the API Key value. 
+
+This will allow use cases that do not require authentication to be successfully executed, but those that do require authentication will fail.

docs/localDevelopment.md

@@ -0,0 +1,95 @@
+# Local Development
+
+To set up your local development environment for working on this project, follow these steps:
+
+## Prerequisites
+
+### Node.js and npm
+
+Make sure you have Node.js and npm installed on your machine.
+
+This package is built using `node v19`, so it is recommended to use that version.
+
+### Docker and Docker Compose
+
+We use [Test Containers](https://github.com/testcontainers/testcontainers-node) for running integration tests.
+
+In our Test Containers setup we use Docker Compose, as our tests involve multiple containers that need to be orchestrated together.
+
+If you want to run integration tests, you need Docker and Docker Compose installed on your machine.
+
+## Install Dependencies
+
+Make sure that you install all the project dependencies:
+
+```bash
+npm install
+```
+
+## Build
+
+In order to build the project, we need to run the following command:
+
+```bash
+npm run build
+```
+
+the build generated will be placed in `dist` folder.
+
+## Tests
+
+### Run all tests
+
+```bash
+npm run test
+```
+
+### Run unit tests
+
+```bash
+npm run test:unit
+```
+
+### Run integration tests
+
+```bash
+npm run test:integration
+```
+
+#### Configure the integration testing environment
+
+The integration testing environment uses different environment variables, defined in a .env file, available in the _test/integration/environment_ folder.
+
+These environment variables can be updated as needed for integration testing. For example, we can specify the Dataverse image registry and tag, to point to the particular Dataverse image to test.
+
+- To test images generated in Dataverse PRs: Set `ghcr.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and the source branch name of a particular PR as the image tag (DATAVERSE_IMAGE_TAG).
+
+- To test the Dataverse develop branch: Set `docker.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and `unstable` as the image tag (DATAVERSE_IMAGE_TAG).
+
+### Run test coverage
+
+```bash
+npm run test:coverage
+```
+
+## Format and lint
+
+### Run formatter
+
+```bash
+npm run format
+```
+
+### Run linter
+
+Running a linting check on the code:
+
+```bash
+npm run lint
+```
+
+Fix linting checks on the code:
+
+```bash
+npm run lint:fix
+```