@loveluthien/carta-frontend 6.0.0-dev

package/docs_website/versioned_docs/version-4.1.0/contributing/github-workflow.md

@@ -0,0 +1,141 @@
+---
+sidebar_position: 2
+---
+
+# GitHub workflow
+
+The workflow for contributing to the codebase.
+
+## Creating new issues
+
+When creating new issues, please refer to [this page](https://github.com/CARTAvis/carta-frontend/labels) for the available labels that can be added.
+
+If the issue is related to bug fixing, please use the [bug report template](https://github.com/CARTAvis/carta-frontend/blob/dev/.github/ISSUE_TEMPLATE/bug_report.md). Please make sure to fill in the template with all the necessary information, including the description, reproduction steps, and platform information. Providing reproduction steps is particularly helpful for resolving issues. Additionally, including testing images can be helpful for reproducing the issue.
+
+## Contributing to the codebase
+
+### Cloning and building the codebase
+
+To clone the codebase to your computer:
+
+```
+git clone git@github.com:CARTAvis/carta-frontend.git
+```
+
+For detailed instructions on building the codebase from source, please refer to the [README file](https://github.com/CARTAvis/carta-frontend/blob/dev/README.md#development).
+
+### Creating a branch
+
+Before making any changes to the codebase, create and check out to a new branch. It's recommended to use the following format for branch names:
+
+```
+git checkout -b "[author]/[issue id]_[description_with_underscores]"
+```
+
+If the issue doesn't exist yet, please create a new issue. When you start working on the issue, update the GitHub Project status of the issue to "In Progress".
+
+### Pushing changes
+
+To stage and commit your changes:
+
+```
+git add .
+git commit -m "a short description of the change"
+```
+
+To push the branch to the remote repository:
+
+```
+git push
+```
+
+### Making a pull request
+
+#### Pull request template
+
+When making a pull request from your branch, please use the [pull request template](https://github.com/CARTAvis/carta-frontend/blob/dev/.github/pull_request_template.md).
+
+In the description section, please provide details about your changes, including linked issues and companion pull requests (if there are), what is implemented or fixed, and how to test it.
+
+Each check item in the checklist section is explained below:
+
+For linked issues (if there are): this section is for checking the status of the issues that are linked in the above description.
+
+-   assignee and label added: assign yourself to the issue you are working on. Add labels to the issue.
+
+-   GitHub Project estimate added: provide an estimate for the time required to complete the issue. This estimation is useful for future development planning.
+
+For the pull request: this section is for checking the status of the pull request and reviewing the code changes.
+
+-   reviewers and assignee added: assign reviewers and an assignee to the pull request. The assignee will be responsible for merging the pull request.
+
+-   GitHub Project estimate added: provide an estimate for the time required to review the pull request.
+
+-   changelog updated / no changelog update needed: updating the changelog is required when the issue exists in the latest release and the changes have an impact on users. It is recommended to update the changelog when sending the pull request and to resolve changelog merge conflicts using the GitHub UI.
+
+-   unit test added (for functions with no dependenies): it is recommended to add unit tests for functions that are related to the code changes.
+
+-   API documentation added (for public variables and methods in stores): it is recommended to add API documentation for public variables and methods in stores that are related to the code changes. Check [here](./documentation-guidelines/#writing-api-documentation) for adding API documentation.
+
+For dependencies: this section is for checking repositories that have dependencies on carta-frontend or are dependencies of carta-frontend.
+
+-   e2e test passing / corresponding fix added: check if the end-to-end tests are passing. This will be checked during the review.
+
+-   protobuf version bumped / no protobuf version bumped needed: updating the protobuf version is required when the behavior of the protobuf messages is changed.
+
+-   protobuf updated to the latest dev commit / no protobuf update needed: updating the protobuf is required when there are changes in the carta-protobuf submodule. This can be done when the pull request is ready for merge. Check [here](#merging-a-pull-request-with-protobuf-changes-required) for the steps.
+
+-   corresponding ICD test fix added (`BackendService` changed) / no ICD test fix needed (`BackendService` unchanged): updating ICD tests is required when there are changes in `BackendService`.
+
+-   user manual prepared (for large new features): preparing user manual updates in advance is required for large new features.
+
+#### CI checks
+
+Please ensure that the CI passes successfully when making the pull request. The CI checks various items:
+
+-   Codebase formatting: Check [here](./developer-tips/#checking-and-fixing-code-format) for automatic codebase formatting.
+-   Production builds with different Node versions: The build will not be successful if the lint check fails. Check [here](./developer-tips/#code-linting) for details.
+-   Documentation page formatting: Check [here](./documentation-guidelines/#formatting) for automatic formatting.
+-   Production build of the documentation website: Details of building the website locally can be found [here](./documentation-guidelines/#building-documentation).
+
+### Merging a pull request
+
+The assignee of the pull request is responsible for merging the pull request. When merging the pull request, ensure the following:
+
+-   Sufficient reviewers have approved the pull request.
+-   All items in the checklist are completed.
+-   All CI checks have passed successfully.
+
+After merging the pull request, make sure to close the linked issue if necessary. GitHub automatically closes issues when they are linked properly. Remember to delete the branch after the merge.
+
+#### Merging a pull request with protobuf changes required
+
+If the pull request requires changes in the carta-protobuf submodule and is ready for merge, follow these steps:
+
+1. Merge the carta-protobuf branch in the repository.
+
+2. Check out the frontend branch:
+
+    ```
+    git checkout [the frontend branch]
+    ```
+
+3. Check out the dev branch of the protobuf submodule and pull the latest version:
+
+    ```
+    cd protobuf
+    git checkout dev
+    git pull
+    cd ..
+    ```
+
+4. Commit and push the changes:
+
+    ```
+    git commit -a -m "update protobuf"
+    git push
+    ```
+
+5. Finally, you can check the item "protobuf updated to the latest dev commit" in the check list. The pull request is ready for merge if all the other checklist items are completed and the CI checks have passed.
+
+6. For the carta-backend repository, follow similar steps for the corresponding backend branch as in steps 2 to 5. Merge the frontend and backend pull requests simultaneously.

package/docs_website/versioned_docs/version-4.1.0/contributing/release-guidelines.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 5
+---
+
+# Release guidelines
+
+In this document, 123 is a placeholder for the current release number, and 124 for the following release number.
+
+## Beta releases
+
+### Beta release
+
+1. `dev` branch: update `CHANGELOG.md`. Change the `Unreleased` heading to `123.0.0-beta.0`.
+2. `dev` branch: update the user manual URL if necessary.
+3. Create a `release/123.0` branch using the `dev` branch.
+4. `release/123.0` branch: update the `package.json` version string to `123.0.0-beta.0`. Run `npm install` to update `package-lock.json`.
+5. Create a `v123.0.0-beta.0` tag using the release branch.
+6. Test the release branch. Make any required fixes in the `dev` branch, and merge them into the release branch. Ideally, bump the version and create a new tag every time changes are merged. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+7. Create packages from the release branch.
+
+### After beta release
+
+1. `dev` branch: update `CHANGELOG.md`. Create a new `Unreleased` section.
+2. `dev` branch: update the documentation website ([guidelines](./documentation-guidelines/#versioning)). Create a new version `123.0.0-beta.0`.
+
+### Additional beta release
+
+This process should be followed if changes have to be made after the beta packages have already been published (or even provided to a limited number of users). If there are significant changes in `dev` that should _not_ be included in the beta release, follow the point release procedure instead (but adjust the version strings as required).
+
+1. Make the required fixes in `dev`.
+2. `dev` branch: update `CHANGELOG.md`. Change the `Unreleased` heading to `123.0.0-beta.1`.
+3. `dev` branch: update the user manual URL if necessary.
+4. Merge the `dev` branch into the `release/123.0` branch.
+5. `release/123.0` branch: update the `package.json` version string to `123.0.0-beta.1`. Run `npm install` to update `package-lock.json`.
+6. Create a `v123.0.0-beta.1` tag using the release branch.
+7. Test the release branch. Make any required fixes in the `dev` branch, and merge them into the release branch. Ideally, bump the version and create a new tag every time changes are merged. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+8. Create packages from the release branch.
+
+## Stable releases
+
+### Final release
+
+1. `dev` branch: update `CHANGELOG.md`. Change the `Unreleased` heading to `123.0.0`.
+2. `dev` branch: update the user manual URL if necessary.
+3. Merge the `dev` branch into the `release/123.0` branch.
+4. `release/123.0` branch: update the `package.json` version string to `123.0.0-rc.0`. Run `npm install` to update `package-lock.json`.
+5. Create a `v123.0.0-rc.0` tag using the release branch.
+6. Test the release branch. Make any required fixes in the `dev` branch, and merge them into the release branch. Ideally, bump the version and create a new tag every time changes are merged. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+7. `release/123.0` branch: update the `package.json` version string to `123.0.0`. Run `npm install` to update `package-lock.json`.
+8. Create a `v123.0.0` tag using the release branch.
+9. Create packages from the release branch.
+
+### After final release
+
+1. `dev` branch: update the `package.json` version string to `124.0.0-dev`. Run `npm install` to update `package-lock.json`.
+2. `dev` branch: update `CHANGELOG.md`. Create a new `Unreleased` section.
+3. `dev` branch: update the documentation website ([guidelines](./documentation-guidelines/#versioning)). Create a new version `123.0.0`.
+
+### Point release
+
+This process should be followed if important bug fixes have to be released after the final release packages have already been published (or even provided to a limited number of users). If there are no changes in `dev` that should not be included in the point release, follow the additional beta release procedure instead (but adjust the version strings as required).
+
+1. Make the required fixes in `dev`. Cherry-pick them into the release branch.
+2. `dev` branch: update `CHANGELOG.md`. Move the cherry-picked changes from the `Unreleased` section to a new `123.0.1` section _under_ `Unreleased`.
+3. `release/123.0` branch: update `CHANGELOG.md`. Copy only the `123.0.1` section from the changelog in the `dev` branch.
+4. `release/123.0` branch: update the `package.json` version string to `123.0.1`. Run `npm install` to update `package-lock.json`.
+5. Create a `v123.0.1` tag using the release branch.
+6. Test the release branch. If an issue affects both `dev` and the release branch, fix it in `dev` and cherry-pick the changes into the release branch. If an issue is caused by changes in `dev` which are not included in the point release, make the minimal required changes in the release branch. Ideally, bump the version and create a new tag every time changes are made. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+7. Create packages from the release branch.
+
+### After point release
+
+-   `dev` branch: update the documentation website ([guidelines](./documentation-guidelines/#versioning)). Replace version `123.0.0` with `123.0.1`.

package/docs_website/versioned_docs/version-4.1.0/contributing/unit-test-guidelines.md

@@ -0,0 +1,79 @@
+---
+sidebar_position: 3
+---
+
+# Unit test guidelines
+
+Guidelines for running and writing unit tests.
+
+## Running unit tests
+
+1. Install package dependencies:
+
+    ```
+    npm install
+    ```
+
+2. Build carta-protobuf and WebAssembly libraries:
+
+    ```
+    npm run build-protobuf
+
+    npm run build-libs
+    npm run build-wrappers
+    ```
+
+3. Run unit tests:
+
+    ```
+    npm test
+    ```
+
+    By default, Jest runs tests related to changed files.
+
+    To display individual test results, use the `--verbose` flag:
+
+    ```
+    npm test --verbose
+    ```
+
+    For more options available in Jest, please refer to the [Jest documentation](https://jestjs.io/docs/cli).
+
+## Writing unit tests
+
+### Structures
+
+-   Directory structure: colocate the test file in the same directory and name with `.test.ts/tsx` suffix. For example,
+    ```
+    .
+    └── src
+        └── components
+            └── AComponent
+                ├── AComponent.tsx
+                ├── AComponent.scss
+                └── AComponent.test.tsx
+        └── utilities
+            └── math
+                ├── math.ts
+                └── math.test.ts
+    ```
+-   Test code structure: use `describe` to structure the tests. For example,
+
+    ```javascript
+    describe("[unit]", () => {
+        test("[expected behavior]", () => {});
+
+        describe("[sub unit]", () => {
+            test("[expected behavior]", () => {});
+        });
+    });
+    ```
+
+-   Make sure to implement low-level tests that focus on a certain class or function. Mock imported classes and functions with Jest when necessary.
+-   TypeScript enum: import TypeScript enum without index files to avoid compile failure.
+
+### Testing React components
+
+-   Avoid mocking blueprint.js objects to prevent having complex setups.
+-   Avoid testing snapshots to prevent having large files in the codebase.
+-   Follow [the order of priority](https://testing-library.com/docs/queries/about/#priority) suggested by React Testing Library when querying elements.

package/docs_website/versioned_docs/version-4.1.0/documents.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Documents
+
+### Table of Contents
+
+-   <DocsIndexLink path="/code-snippet-tutorial">
+        <h4>Code snippet tutorial</h4>
+    </DocsIndexLink>
+-   <DocsIndexLink path="/contributing">
+        <h4>Contributing</h4>
+    </DocsIndexLink>

package/docs_website/versioned_docs/version-5.0.0/api-packages.json

@@ -0,0 +1 @@
+[{"entryPoints":{"index":{"path":"src/index.tsx","entry":"."},"components":{"path":"src/components/index.ts","entry":".","label":"Components"},"components/Dialogs":{"path":"src/components/Dialogs/index.ts","entry":".","label":"Components - Dialogs"},"components/Shared":{"path":"src/components/Shared/index.ts","entry":".","label":"Components - Shared"},"models":{"path":"src/models/index.ts","entry":".","label":"Models"},"services":{"path":"src/services/index.ts","entry":".","label":"Services"},"stores":{"path":"src/stores/index.ts","entry":".","label":"Stores"},"utilities":{"path":"src/utilities/index.ts","entry":".","label":"Utilities"}},"packagePath":".","packageSlug":".","packageName":"carta-frontend","packageVersion":"5.0.0"}]