mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-03-15 04:06:33 +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
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue