mirror of
https://github.com/danny-avila/LibreChat.git
synced 2025-12-16 16:30:15 +01:00
🧑💻docs: Update General Docs and Contribution Guidelines (#2194)
* doc upddate: documentation_guidelines.md * doc upddate: how_to_contribute.md * doc upddate: testing.md / how_to_contribute.md * doc upddate: translation_contribution.md/testing.md/how_to_contribute.md * doc upddate: coding_conventions.md * fix formatting: how_to_contribute.md * fix formatting (again) : how_to_contribute.md
This commit is contained in:
Fuegovic
GitHub
parent
f86d80de59
commit
a4f4ec85f8
7 changed files with 283 additions and 106 deletions
|
|
@ -3,11 +3,12 @@ title: 🧑💻 Code Standards and Conventions
|
|||
description: This guide covers the best practices for JavaScript coding, such as following the Airbnb Style Guide, using CommonJS modules, structuring the API using Express, Mongoose, and services, and testing and documenting the code using Jest, Supertest, Playwright, JSDoc, and TypeScript.
|
||||
weight: -7
|
||||
---
|
||||
|
||||
# Coding Conventions
|
||||
|
||||
## Node.js API Server
|
||||
|
||||
### 1. General Guidelines
|
||||
### General Guidelines
|
||||
|
||||
- Follow the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) for general JavaScript coding conventions.
|
||||
- Use "clean code" principles, such as keeping functions and modules small, adhering to the single responsibility principle, and writing expressive and readable code.
|
||||
|
|
@ -17,7 +18,7 @@ weight: -7
|
|||
- Use CommonJS modules (require/exports) for Node.js modules.
|
||||
- Organize and modularize the codebase using separate files for different concerns.
|
||||
|
||||
### 2. API Design
|
||||
### API Design
|
||||
|
||||
- Follow RESTful principles when designing APIs.
|
||||
- Use meaningful and descriptive names for routes, controllers, services, and models.
|
||||
|
|
@ -28,7 +29,7 @@ weight: -7
|
|||
- Use the logging system included in the `utils` directory to log important events and errors.
|
||||
- Do JWT-based, stateless authentication using the `requireJWTAuth` middleware.
|
||||
|
||||
### 3. File Structure
|
||||
### File Structure
|
||||
|
||||
*Note: The API is undergoing a refactor to separate out the code for improved separation of concerns, testability, and maintainability. Any new APIs must follow the structure using the auth system as an example, which separates out the routes, controllers, services, and models into separate files.*
|
||||
|
||||
|
|
@ -66,7 +67,7 @@ Defines Mongoose models to represent data entities and their relationships.
|
|||
- Include only the necessary fields, indexes, and validations in the models.
|
||||
- Keep models independent of the API layer by avoiding direct references to request/response objects.
|
||||
|
||||
### 4. Database Access (MongoDB and Mongoose)
|
||||
### Database Access (MongoDB and Mongoose)
|
||||
|
||||
- Use Mongoose ([https://mongoosejs.com](https://mongoosejs.com)) as the MongoDB ODM.
|
||||
- Create separate model files for each entity and ensure clear separation of concerns.
|
||||
|
|
@ -74,7 +75,7 @@ Defines Mongoose models to represent data entities and their relationships.
|
|||
- Handle database connections efficiently and avoid connection leaks.
|
||||
- Use Mongoose query builders to create concise and readable database queries.
|
||||
|
||||
### 5. Testing and Documentation
|
||||
### Testing and Documentation
|
||||
|
||||
*Note: the repo currently lacks sufficient automated unit and integration tests for both the client and the API. This is a great first issue for new contributors wanting to familiarize with the codebase.*
|
||||
|
||||
|
|
|
|||
|
|
@ -10,26 +10,29 @@ This document explains how to contribute to the LibreChat documentation by writi
|
|||
|
||||
## New Documents
|
||||
|
||||
- Use lowercase letters and underscores to name new document files (e.g., `documentation_guidelines.md`).
|
||||
- For new features, create new documentation and place it in the relevant folder/sub-folder under `../docs`.
|
||||
- Use ^^lowercase letters^^ and ^^underscores^^ to name new document files (e.g.: ==documentation_guidelines.md==).
|
||||
- For new features, create new documentation and place it in the relevant folder/sub-folder under ==../docs==.
|
||||
- If the feature adds new functionality, add it to the appropriate section in the main `README.md` and `../docs/index.md`.
|
||||
- When creating a new document, **add it to the table of contents in the `index.md` file of the folder where your document is located.**
|
||||
|
||||
## Markdown Formatting
|
||||
|
||||
- Use `#`, `##`, and `###` for headings and subheadings.
|
||||
- Use `#`, `##`, and `###` for headings and subheadings.
|
||||
- Use `#` for the document title.
|
||||
- ❗ **Only one main title per document is allowed**
|
||||
- Use `##` for the main sections of the document.
|
||||
- Use `###` for the sub-sections within a section.
|
||||
- Use `**` to make text **bold** and highlight important information (do not use in place of a heading).
|
||||
- Use relative paths for links to other documents.
|
||||
- You can use HTML to add additional features to a document.
|
||||
- Highlight keystrokes with `+` (example: `++ctrl+alt+del++` 🟰 ++ctrl+alt+del++)
|
||||
- 🌐 see the MKDocs Material documentation for more information: [MKDocs Material Reference](https://squidfunk.github.io/mkdocs-material/reference/)
|
||||
|
||||
## Document Metadata
|
||||
|
||||
- Add metadata in the header of your document following this format:
|
||||
|
||||
```yaml
|
||||
```yaml title="metadata example:"
|
||||
---
|
||||
title: 😊 Document Title
|
||||
description: This description will be used in social cards and search engine results.
|
||||
|
|
@ -41,32 +44,37 @@ weight: 0
|
|||
- `description:` A brief description of the document's content.
|
||||
- `weight:` Setting the weight in the document metadata will influence its position in the table of contents. Lowest weights are placed first. If not set, it defaults to `0`. When multiple docs have the same weight, they are sorted alphabetically.
|
||||
|
||||
## Important Notes
|
||||
!!! warning "Important Notes"
|
||||
|
||||
- **⚠️Keep the documentation organized and structured⚠️**
|
||||
- Do not add unrelated information to an existing document. Create a new one if needed.
|
||||
- Upload all assets (images, files) directly from GitHub's web interface when editing the document.
|
||||
- 🗃️ **Keep the documentation organized and structured**
|
||||
- 🙅 Do not add unrelated information to an existing document. Create a new one if needed.
|
||||
- 📌 Upload all assets (images, files) directly from GitHub when editing the document (see tip below).
|
||||
|
||||
> **Tip:** Go to the LibreChat repository, find a conversation, and paste an image from your clipboard into the text input box. It will automatically be converted into a URL you can use in your document. (Then exit the page without actually posting the comment.😉)
|
||||
??? tip "Upload Assets on GitHub"
|
||||
|
||||
> Get the link from a text input box:
|
||||
> 
|
||||
> Or upload directly from the web UI:
|
||||
> 
|
||||
!!! example "Example"
|
||||
- Go to the LibreChat repository, find a conversation, and paste an image from your clipboard into the text input box. It will automatically be converted into a URL you can use in your document. (Then exit the page without actually posting the comment.😉)
|
||||
|
||||
Get the link from a text input box:
|
||||
|
||||
|
||||
!!! example "Alternative method"
|
||||
Upload directly from the web UI:
|
||||
|
||||
|
||||
## Testing New Documents
|
||||
|
||||
- When adding new documents, it is important to test them locally using MkDocs to ensure correct formatting and proper organization in the table of contents (index.md and the left panel of the category).
|
||||
- When adding new documents, it is important to test them locally using MkDocs to ensure correct formatting and proper organization in the table of contents: specifically in **index.md** and in the **left panel** of each category. Make sure the document position match in both.
|
||||
|
||||
### Setup MkDocs Locally
|
||||
|
||||
- Requirement: Python 3.3 and later (on older versions you will need to install virtualenv)
|
||||
- Requirement: **Python 3.3** and later (on older versions you will need to install virtualenv)
|
||||
|
||||
#### Material for MkDocs Installation
|
||||
|
||||
- We are using MkDocs Material and multiple plugins. All of them are required to properly test new documentation.
|
||||
|
||||
```sh
|
||||
```sh title="Install Requirements:"
|
||||
python -m venv .venv
|
||||
. .venv/bin/activate
|
||||
pip install -r ./docs/src/requirements.txt
|
||||
|
|
@ -76,25 +84,28 @@ pip install -r ./docs/src/requirements.txt
|
|||
|
||||
- Use this command to start MkDocs:
|
||||
|
||||
```sh
|
||||
```sh title="Start MKDocs:"
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
- Look for any errors in the console logs and fix them if possible.
|
||||
- Access the locally running documentation website at `http://127.0.0.1:8000/`.
|
||||
- ✅ Look for any errors in the console logs and fix them whenever possible.
|
||||
- 🌐 Access the locally running documentation website at `http://127.0.0.1:8000/`.
|
||||
|
||||
|
||||
|
||||
## Tips
|
||||
|
||||
- You can check the code of this document to see how it works.
|
||||
- You can run MkDocs locally to test more extensive documentation changes.
|
||||
- You can ask GPT or Bing for help with proofreading, syntax, and markdown formatting.
|
||||
!!! tip "Tips"
|
||||
|
||||
- You can check the code of this document to see how it works.
|
||||
- You should run MkDocs locally to test more extensive documentation changes.
|
||||
- You can ask GPT, Claude or any other AI for help with proofreading, syntax, and markdown formatting.
|
||||
|
||||
---
|
||||
|
||||
### Example of HTML image embedding:
|
||||
## Example of HTML image embedding:
|
||||
|
||||
```html title="HTML Code"
|
||||
<p align="center">
|
||||
<a href="https://discord.librechat.ai">
|
||||
<img src="https://github.com/danny-avila/LibreChat/assets/32828263/45890a7c-5b8d-4650-a6e0-aa5d7e4951c3" height="128" width="128">
|
||||
|
|
@ -103,3 +114,14 @@ mkdocs serve
|
|||
<h3 align="center">LibreChat</h3>
|
||||
</a>
|
||||
</p>
|
||||
```
|
||||
|
||||
!!! quote "Result:"
|
||||
<p align="center">
|
||||
<a href="https://discord.librechat.ai">
|
||||
<img src="https://github.com/danny-avila/LibreChat/assets/32828263/45890a7c-5b8d-4650-a6e0-aa5d7e4951c3" height="128" width="128">
|
||||
</a>
|
||||
<a href="https://librechat.ai">
|
||||
<h3 align="center">LibreChat</h3>
|
||||
</a>
|
||||
</p>
|
||||
|
|
|
|||
|
|
@ -1,69 +1,204 @@
|
|||
---
|
||||
title: 🙌 Beginner's Guide to Contributions
|
||||
title: 🙌 Getting Started for Contributors
|
||||
description: Learn how to use GitHub Desktop, VS Code extensions, and Git rebase to contribute in a quick and easy way.
|
||||
weight: -10
|
||||
---
|
||||
# How to Contribute in a Quick and Easy Way
|
||||
> **❗Note:** If you are not familiar with the concept of repo, PR (pull request), fork and branch, start by looking at the official GitHub documentation on the subject:
|
||||
[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)
|
||||
|
||||
## Installation of Tools
|
||||
# Getting Started for Contributors
|
||||
!!! danger "Important:"
|
||||
- 📚 If you're new to concepts like **repositories**, **pull requests (PRs)**, **forks**, and **branches**, begin with the official GitHub documentation:
|
||||
- [Getting Started - About Collaborative Development Models](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)
|
||||
- 🌐 For contributing translations, refer to:
|
||||
- [Contribute a Translation](./translation_contribution.md)
|
||||
- 💻 To understand our coding standards, see:
|
||||
- [Coding Conventions](./coding_conventions.md)
|
||||
- 👥 Our contributor guidelines can be found at:
|
||||
- [Contributor Guidelines](https://github.com/danny-avila/LibreChat/blob/main/.github/CONTRIBUTING.md)
|
||||
- 📝 For updates and additions to documentation, please review:
|
||||
- [Documentation Guidelines](./documentation_guidelines.md)
|
||||
- 🧪 Consult the following guide to perform local tests before submitting a PR:
|
||||
- [Local Test Guide](./testing.md)
|
||||
|
||||
1. [Git](https://git-scm.com/downloads) is essential, the first thing to download.
|
||||
2. [Git LFS](https://git-lfs.com/) can be useful for uploading files with larger sizes.
|
||||
3. [Github Desktop](https://desktop.github.com/) - I use it only for UI; I don't recommend using it for pushing or other actions.
|
||||
## Requirements
|
||||
|
||||
## How to Use?
|
||||
1. ✅ [Git](https://git-scm.com/downloads) - ^^Essential^^
|
||||
2. ✅ [Node.js](https://nodejs.org/en/download) - ^^Essential^^, use the LTS version
|
||||
3. ✅ [Git LFS](https://git-lfs.com/) - ^^Useful^^ for uploading files with larger sizes.
|
||||
4. ✅ [Github Desktop](https://desktop.github.com/) - ^^Optional^^
|
||||
5. ✨ [VSCode](https://code.visualstudio.com/Download) - ^^Recommended^^ Source-code Editor
|
||||
6. 🐳 [Docker Desktop](https://www.docker.com/products/docker-desktop/) - ^^Recommended^^ (more on that later)
|
||||
|
||||
This will be a somewhat raw text, but I'll try to be as clear as possible.
|
||||
### Recommended VSCode extensions
|
||||
|
||||
I recommend installing the following extensions in VS Code:
|
||||
It is recommended to install the following extensions in VS Code:
|
||||
|
||||
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
|
||||
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
|
||||
- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)
|
||||
|
||||
### Example of a Pull Request (PR)
|
||||
## Prepare the Environment
|
||||
|
||||
Let's say I want to add another page for an API Panel.
|
||||
??? question "npm vs Docker"
|
||||
|
||||
1. Open GitHub and select Danny's fork.
|
||||
2. First, make sure that the main branch is clean with no commits and up to date.
|
||||
|
||||
3. Open "View all my branches" and create a new branch with a descriptive name for your task. For example: "ApiPanel."
|
||||
4. In GitHub Desktop, select the branch you just created.
|
||||
|
||||
5. Start modifying the code, and when you finish a part, commit the changes.
|
||||
Example of commits:
|
||||
- commit1: Created the frontend
|
||||
- commit2: Fixed a bug in variable export
|
||||
- commit3: Removed unnecessary comments and added translation support
|
||||
- and so on...
|
||||
While Docker is our preferred method for installing LibreChat due to its ease of setting up and consistency across different environments, we strongly recommend using npm for development purposes. This recommendation is based on several advantages that npm offers for developers:
|
||||
|
||||
## Testing
|
||||
- Faster Iteration: npm allows for quicker iteration cycles during development. Changes made to the codebase can be immediately reflected without the need to rebuild the entire Docker image, leading to a more efficient development process.
|
||||
- Direct Dependency Management: Using npm gives developers direct control over the dependencies. It’s easier to install, update, or remove packages, and manage project dependencies in real-time, which is crucial for development.
|
||||
- Simplified Debugging: Debugging is more straightforward with npm, as developers can directly interact with the code and tools without the abstraction layer that Docker introduces. This direct interaction facilitates easier identification and resolution of issues.
|
||||
- Native Environment: Developing with npm allows the application to run in its native environment on your machine. This can help in catching environment-specific issues early in the development cycle.
|
||||
|
||||
While testing the code, if you're working with the frontend, it might be frustrating to run `npm run frontend` and `npm run backend` every time. Instead, use `npm run frontend:dev` to see real-time changes on port 3090 (really!).
|
||||
For these reasons, while Docker remains the recommended installation method for production and distribution due to its containerization benefits, npm is the preferred choice for development within the LibreChat ecosystem.
|
||||
|
||||
> Note: You must run `npm run frontend` once before you can use `npm run frontend:dev`
|
||||
### GitHub
|
||||
|
||||
### How?
|
||||
- Fork the LibreChat repository: [https://github.com/danny-avila/LibreChat/fork](https://github.com/danny-avila/LibreChat/fork)
|
||||
|
||||
- `git add *` adds all files to be committed.
|
||||
- `git commit -m "name-of-your-commit"` creates a commit.
|
||||
- `git push` uploads the changes.
|
||||
- Create a branch on your fork, give it a proper name and point it to the original repository
|
||||
??? info "Screenshots:"
|
||||
|
||||
|
||||
|
||||
|
||||
Before doing all this, I recommend using GitHub Desktop to see what you've changed.
|
||||
|
||||
- Download your new branch on your local pc
|
||||
|
||||
If `git commit` fails due to ESLint errors, read the error message and understand what's wrong. It could be an unused variable or other issues.
|
||||
!!! quote ""
|
||||
|
||||
### Possible Various Problems
|
||||
```sh title="Download your LibreChat branch"
|
||||
git clone -b branch-name https://github.com/username/LibreChat.git
|
||||
```
|
||||
|
||||
!!! warning "note:"
|
||||
replace `branch-name` and `username` with your own
|
||||
|
||||
If you have the main branch with many commits and don't know what to do, follow this simple guide:
|
||||
### Open it in VS Code
|
||||
- Once you successfully cloned your branch
|
||||
- Navigate to the LibreChat folder:
|
||||
```sh
|
||||
cd LibreChat
|
||||
```
|
||||
- Open it in VS Code:
|
||||
```sh
|
||||
code .
|
||||
```
|
||||
|
||||
⚠️ Please do this only when you have no active PRs or when you're not working on the project:
|
||||
### Prepare LibreChat
|
||||
|
||||
1. Do a pull origin and in the terminal write `git log` to identify how many commits you are behind.
|
||||
2. Use `git rebase -i HEAD~2`, where 2 represents the number of commits you need to go back. If you need to go back 100 commits, use `git rebase -i HEAD~100`.
|
||||
3. In the editor, change the "pick" for the two commits to "drop," save with "esc," then type `:wq` and press "Enter."
|
||||
4. Finally, run `git push --force origin main`.
|
||||
- Open the terminal in vscode with ++ctrl+shift+grave++
|
||||
- Alternatively you can use ++ctrl+j++ to open the bottom pane and select the terminal from there
|
||||
|
||||
- Install the LibreChat depencencies
|
||||
- ```
|
||||
npm ci
|
||||
```
|
||||
- ```
|
||||
npm run frontend
|
||||
```
|
||||
- .env Configuration
|
||||
- Create the ==.env== file. If you dont have one handy, you can duplicate the ==.env.example== file and configure it.
|
||||
|
||||
!!! warning ".env"
|
||||
The default values in the example file should be fine, except for `MONGO_URI`. You will need to provide your own. You can use [MongoDB Community Server](https://www.mongodb.com/try/download/community), [MongoDB Atlas Cloud](https://www.mongodb.com/cloud/atlas/register), see this doc to setup Mongodb Atlas Cloud: [Online MongoDB](../install/configuration/mongodb.md).
|
||||
|
||||
You can also enable verbose server output in the console with `DEBUG_CONSOLE` set to true.
|
||||
|
||||
### Development Workflow
|
||||
|
||||
To efficiently work on LibreChat, use the following commands:
|
||||
|
||||
- **Starting the Backend:**
|
||||
- Use `npm run backend` to start LibreChat normally.
|
||||
- For active development, `npm run backend:dev` will monitor backend changes.
|
||||
- Access the running application at `http://localhost:3080/`.
|
||||
|
||||
- **Running the Frontend in Development Mode:**
|
||||
- ❗**Ensure the backend is also running.**
|
||||
- Execute `npm run frontend:dev` to actively monitor frontend changes.
|
||||
- View the frontend in development mode at `http://localhost:3090/`.
|
||||
|
||||
!!! tip "Pro Tip:"
|
||||
To avoid the hassle of restarting both frontend and backend during frontend development, simply run `npm run frontend:dev` for real-time updates on port 3090.
|
||||
|
||||
## Perform Tests Locally
|
||||
Before submitting your updates, it’s crucial to verify they pass all tests. Follow these steps to run tests locally, see: [Perform Tests Locally](./testing.md)
|
||||
|
||||
By running these tests, you can ensure your contributions are robust and ready for integration.
|
||||
|
||||
## Commit, Push, Pull Request (PR)
|
||||
|
||||
### Make a Commit
|
||||
|
||||
**Commits** should be made when you reach a logical checkpoint in your development process. This could be after a new feature is added, a bug is fixed, or a set of related changes is completed. Each commit should contain a clear message that explains what changes have been made and why.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add login functionality"
|
||||
```
|
||||
|
||||
### Push Changes
|
||||
|
||||
You should **push** your changes to the remote repository after a series of commits that complete a feature or fix a known issue. Pushing often helps to ensure that your changes are safely stored remotely and makes collaboration with others easier.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
git push origin feature-branch-name
|
||||
```
|
||||
|
||||
### Make a Pull Request (PR)
|
||||
|
||||
A **Pull Request** should be made when you want to merge your changes from a feature branch into the main branch. Before creating a PR, make sure to:
|
||||
|
||||
1. Pull the latest changes from the main branch and resolve any conflicts.
|
||||
2. Push your updated feature branch.
|
||||
3. Ensure your code adheres to the project's style and contribution guidelines.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout feature-branch-name
|
||||
git merge main
|
||||
# Resolve conflicts if any
|
||||
git push origin feature-branch-name
|
||||
# Now go to GitHub and open a pull request
|
||||
```
|
||||
When you are ready, open your repository in a browser and click on "Contribute"
|
||||
|
||||
|
||||
!!! info "Note:"
|
||||
Remember to provide a detailed description in your PR that explains the changes and the value they add to the project. It's also good practice to reference any related issues.
|
||||
|
||||
!!! tip
|
||||
You can use GitHub Desktop to monitor what you've changed.
|
||||
|
||||
|
||||
!!! warning
|
||||
If `git commit` fails due to ESLint errors, read the error message and understand what's wrong. It could be an unused variable or other issues.
|
||||
|
||||
## Reverting Commits Safely
|
||||
|
||||
If you need to undo changes in your feature branch, proceed with caution. This guide is for situations where you have commits that need to be removed and there are no open Pull Requests (PRs) or ongoing work on the branch.
|
||||
|
||||
!!! danger "Warning"
|
||||
Force pushing can rewrite history and potentially disrupt the workflow for others. Use this method only as a last resort.
|
||||
|
||||
1. Update your local repository with the latest changes from the feature branch:
|
||||
```bash
|
||||
git pull origin feature-branch-name
|
||||
```
|
||||
2. Review the commit history to determine how many commits to revert:
|
||||
```bash
|
||||
git log
|
||||
```
|
||||
3. Start an interactive rebase session for the last `N` commits you wish to revert:
|
||||
```bash
|
||||
git rebase -i HEAD~N
|
||||
```
|
||||
Replace `N` with the number of commits you want to go back, such as `2` for two commits or `100` for a hundred.
|
||||
|
||||
4. In the interactive editor, replace `pick` with `drop` for the commits you want to remove. Then save and exit the editor (usually with ++esc++ followed by typing `:wq`).
|
||||
|
||||
5. Force push the changes to the remote repository:
|
||||
```bash
|
||||
git push --force origin feature-branch-name
|
||||
```
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ weight: 5
|
|||
---
|
||||
# Contributing to LibreChat
|
||||
|
||||
* 🙌 [Beginner's Guide to Contributions](./how_to_contribute.md)
|
||||
* 🙌 [Getting Started for Contributors](./how_to_contribute.md)
|
||||
* 🚸 [Contributor Guidelines](https://github.com/danny-avila/LibreChat/blob/main/.github/CONTRIBUTING.md)
|
||||
* 📝 [Documentation Guidelines](documentation_guidelines.md)
|
||||
* 🌍 [Contribute a Translation](translation_contribution.md)
|
||||
|
|
|
|||
|
|
@ -6,7 +6,24 @@ weight: -6
|
|||
|
||||
# Locally test the app during development
|
||||
|
||||
## WIP
|
||||
## Local Unit Tests
|
||||
|
||||
Before submitting your updates, it’s crucial to verify they pass all unit tests. Follow these steps to run tests locally:
|
||||
|
||||
- copy your `.env.example` file in the `/api` folder and rename it to `.env`
|
||||
```bash
|
||||
cp .env.example ./api/.env
|
||||
```
|
||||
- add `NODE_ENV=CI` to your `/api/.env` file
|
||||
- `npm run test:client`
|
||||
- `npm run test:api`
|
||||
|
||||
!!! failure "Warning"
|
||||
When executed locally, this API unit test is expected to fail. This should be the only error encountered.
|
||||
|
||||
|
||||
|
||||
<!-- ## WIP
|
||||
|
||||
## Run the tests
|
||||
|
||||
|
|
@ -25,6 +42,6 @@ weight: -6
|
|||
|
||||
If everything goes well, you should see a `passed` message.
|
||||
|
||||
|
||||
 -->
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ weight: -8
|
|||
## Language Translation
|
||||
|
||||
### Preparation
|
||||
Fork the [LibreChat repository](https://github.librechat.ai) and download it using git clone
|
||||
Fork the [LibreChat repository](https://github.librechat.ai) and download it using git clone. See: [Getting Started for Contributors - GitHub](./how_to_contribute.md#github)
|
||||
|
||||
### Add your language to `Translation.tsx`:
|
||||
- Navigate to the `client\src\localization` folder and open the `Translation.tsx` file
|
||||
|
|
@ -41,7 +41,7 @@ Example (English): `'en-US': English,`
|
|||
|
||||
- Copy all the content from `Eng.tsx` into your file and modify it as follows:
|
||||
|
||||
```js
|
||||
```js title="Eng.tsx"
|
||||
// your-language-name phrases
|
||||
|
||||
export default {
|
||||
|
|
@ -52,7 +52,7 @@ Example (English): `'en-US': English,`
|
|||
__Translate only the part after the `:`.__
|
||||
Example:
|
||||
|
||||
```js
|
||||
```js title="**.tsx (new language)"
|
||||
// my-language phrases
|
||||
|
||||
export default {
|
||||
|
|
@ -61,19 +61,22 @@ Example (English): `'en-US': English,`
|
|||
};
|
||||
```
|
||||
|
||||
⚠️ Do not modify the `com_...` part ⚠️
|
||||
!!! warning
|
||||
Do not modify the `com_...` part
|
||||
|
||||
### Delete the Language list after `com_nav_setting_general: 'General',` near the bottom of the file (You do not need to translate the individual language names), except for `com_nav_setting_data: 'Data controls'` (you need to translate it)
|
||||
!!! success "Important:"
|
||||
- Delete the Language list after `com_nav_setting_general: 'General',` near the bottom of the file (You do not need to translate the individual language names)
|
||||
- Do not delete `com_nav_setting_data: 'Data controls'` (you need to translate it)
|
||||
|
||||
|
||||
### Add your language to `Eng.tsx`
|
||||
Open `Eng.tsx` and add your language to the language list in the bottom of the document.
|
||||
|
||||
### Add your language to the menu
|
||||
To add your language to the menu, open the file `client\src\components\Nav\SettingsTabs\General.tsx`.
|
||||
Add your language to the `LangSelector` variable in the following way:
|
||||
- Navigate to the file `client\src\components\Nav\SettingsTabs\General.tsx`.
|
||||
- Add your language to the `LangSelector` variable in the following way:
|
||||
|
||||
```js
|
||||
```js title="LangSelector"
|
||||
export const LangSelector = ({
|
||||
//other code
|
||||
<option value="en-US">{localize(lang, 'com_nav_lang_english')}</option>
|
||||
|
|
@ -84,9 +87,9 @@ export const LangSelector = ({
|
|||
);
|
||||
};
|
||||
```
|
||||
|
||||
Where `**-**` is the local identifier of your language and `com_nav_lang_your-language-name` stands for the name of your language.
|
||||
Example: `com_nav_lang_english` or `com_nav_lang_italian`
|
||||
!!! note
|
||||
`**-**` is the local identifier of your language and `com_nav_lang_your-language-name` stands for the name of your language.
|
||||
Example: `com_nav_lang_english` or `com_nav_lang_italian`
|
||||
|
||||
**You should only need to add one line of code:**
|
||||
```js
|
||||
|
|
@ -94,27 +97,22 @@ Example: `com_nav_lang_english` or `com_nav_lang_italian`
|
|||
```
|
||||
|
||||
### Summary
|
||||
If you followed everything you should have __one__ new file and __3__ files with modifications:
|
||||
If you followed everything you should have ^^**one new file**^^ and ^^**3 modified files**^^:
|
||||
|
||||
```bash
|
||||
new file: client/src/localization/languages/**.tsx <-----new language
|
||||
modified: client/src/components/Nav/SettingsTabs/General.tsx
|
||||
modified: client/src/localization/Translation.tsx
|
||||
modified: client/src/localization/languages/Eng.tsx
|
||||
new file: client/src/localization/languages/**.tsx <-----new language
|
||||
modified: client/src/components/Nav/SettingsTabs/General.tsx
|
||||
modified: client/src/localization/Translation.tsx
|
||||
modified: client/src/localization/languages/Eng.tsx
|
||||
```
|
||||
|
||||
You can confirm this by using the following command: `git status`
|
||||
!!! tip
|
||||
You can confirm this by using the following command: `git status`
|
||||
|
||||
### Commit and create a new PR
|
||||
- Commit your changes using:
|
||||
- `git add *`
|
||||
- `git commit -m "Language translation: your-language translation"`
|
||||
- `git push`
|
||||
|
||||
- Open your repository in a browser and click on "Contribute"
|
||||
See: [Make a PR](./how_to_contribute.md#make-a-pull-request-pr)
|
||||
|
||||
|
||||
|
||||
- Answer all the questions, and in the "Type of Change" section, add `- [x] Translation support`
|
||||
- Delete irrelevant comments from the template
|
||||
- Create a pull request 🎉
|
||||
!!! success "Pull Request"
|
||||
- Answer all the questions, and in the "Type of Change" section, check `- [x] Translation update`
|
||||
- **Delete irrelevant comments** from the PR template
|
||||
- Create a pull request 😎
|
||||
|
|
|
|||
14
mkdocs.yml
14
mkdocs.yml
|
|
@ -65,7 +65,11 @@ markdown_extensions:
|
|||
custom_checkbox: true
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
- pymdownx.critic
|
||||
- pymdownx.caret
|
||||
- pymdownx.mark
|
||||
- pymdownx.tilde
|
||||
- pymdownx.keys
|
||||
- attr_list
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
|
|
@ -74,22 +78,23 @@ markdown_extensions:
|
|||
|
||||
plugins:
|
||||
- search
|
||||
# - pub-debugger # <- General purpose mkdocs debugger
|
||||
# - pub-debugger # <- Uncomment to enable a general purpose mkdocs debugger
|
||||
- mkdocs-nav-weight:
|
||||
# https://github.com/shu307/mkdocs-nav-weight?tab=readme-ov-file
|
||||
section_renamed: true # If true, section name will use the title of its index instead of the folder name.
|
||||
index_weight: -10
|
||||
warning: true # Controls whether to send a Warning when invalid values are detected in markdown metadata
|
||||
reverse: false # If true, sort nav by weight from largest to smallest.
|
||||
headless_included: false
|
||||
# for more info: https://github.com/shu307/mkdocs-nav-weight?tab=readme-ov-file
|
||||
- pub-social:
|
||||
# https://github.com/mkusz/mkdocs-publisher
|
||||
og:
|
||||
enabled: true
|
||||
locale: en_us
|
||||
twitter:
|
||||
enabled: true
|
||||
# for more info: https://github.com/mkusz/mkdocs-publisher
|
||||
- exclude:
|
||||
# https://github.com/apenwarr/mkdocs-exclude
|
||||
glob:
|
||||
- dev/* # <- exclude the docs/dev folder from the docs
|
||||
- "*.tmp"
|
||||
|
|
@ -97,7 +102,6 @@ plugins:
|
|||
- "*.gz"
|
||||
regex:
|
||||
- '.*\.(tmp|bin|tar)$'
|
||||
# https://github.com/apenwarr/mkdocs-exclude
|
||||
|
||||
extra:
|
||||
social:
|
||||
|
|
@ -121,4 +125,4 @@ extra:
|
|||
name: Hugging Face
|
||||
|
||||
copyright:
|
||||
© 2023 <a href="https://librechat.ai/" target="_blank" rel="noopener">LibreChat</a>
|
||||
© 2024 <a href="https://librechat.ai/" target="_blank" rel="noopener">LibreChat</a>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue