Skip to content

Latest commit

 

History

History
252 lines (175 loc) · 15.1 KB

CONTRIBUTING.md

File metadata and controls

252 lines (175 loc) · 15.1 KB
Raw

Contributing to Pear AI

This is the main app for PearAI. The bulk of the functionality is within extension/pearai-submodule, so most of the contributions would be in there.

PearAI is a fork of VSCode (and Continue), so we can simply follow most of VSCode's guide for running the app (see below).

After cloning and building the repo, check out the issues list. Issues labeled good first issue are great candidates to pick up if you are in the code for the first time. If you are contributing significant changes, or if the issue is already assigned to a specific month milestone, please discuss with the assignee of the issue first (in Discord) before starting to work on the issue.

Prerequisites

In order to download necessary tools, clone the repository, and install dependencies via yarn (you need internet access).

You'll need the following tools:

  • Rust/Cargo
  • Git
  • Node.JS, x64, version =20.X.X
  • Yarn 1, version >=1.10.1 and <2, follow the installation guide
  • Python (required for node-gyp; check the node-gyp readme for the currently supported Python versions)
    • Note: Python will be automatically installed for Windows users through installing windows-build-tools npm module (see below)
  • A C/C++ compiler tool chain for your platform:
    • For Windows 10/11
      • Install the Windows Build Tools:
        • if you install Node on your system using the Node installer from the Node.JS page then ensure that you have installed the 'Tools for Native Modules'. Everything should work out of the box then.
        • if you use a node version manager like nvm or nvs then follow these steps: 
           [1] Desktop development with C++
 [2] MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (v14.39-17.9)
      • Warning: Make sure your profile path only contains ASCII letters, e.g. John, otherwise, it can lead to node-gyp usage problems (nodejs/node-gyp/issues#297)
      • Note: Building and debugging via the Windows subsystem for Linux (WSL) is currently not supported.
    • For Windows WSL2: https://github.com/microsoft/vscode/wiki/Selfhosting-on-Windows-WSL
    • For macOS
      • Xcode and the Command Line Tools, which will install gcc and the related toolchain containing make
        • Run xcode-select --install to install the Command Line Tools
    • For Linux
      • On Debian-based Linux: sudo apt-get install build-essential g++ libx11-dev libxkbfile-dev libsecret-1-dev libkrb5-dev python-is-python3
      • On Red Hat-based Linux: sudo yum groupinstall "Development Tools" && sudo yum install libX11-devel.x86_64 libxkbfile-devel.x86_64 libsecret-devel krb5-devel # or .i686.
      • Others:
      • Building deb and rpm packages requires fakeroot and rpm; run: sudo apt-get install fakeroot rpm

Build and Run

The first time you clone the repo, you can:

In PearAI or VSCode, Command Palette and type Run Task then select setup-environment

You can also:

macOS and Linux
 ./scripts/pearai/setup-environment.sh
Windows
.\scripts\pearai/setup-environment.ps1

(If not first time running) Update dependencies

macOS and Linux
./scripts/pearai/install-dependencies.sh
Windows
yarn

Run

Running on Electron with extensions run in NodeJS:

macOS and Linux
./scripts/code.sh
Windows
  • If first time installing, run
.\scripts\code.bat
  • On consecutive runs, we recommned downloading Git Bash, and running the same command as linux/mac to run the app (./scripts/code.sh), because it is faster.

*Info: the reason is because the symlinking must be performed within the code.bat file on Windows on the first run. But on consecutive runs the symlink will already be created, so you can use the faster script which is code.sh

👉 Tip! If you receive an error stating that the app is not a valid Electron app, it probably means you didn't run yarn watch first.

Troubleshooting:

In case of issues, try deleting the contents of ~/.node-gyp (alternatively ~/.cache/node-gyp for Linux, ~/Library/Caches/node-gyp/ for macOS, or %USERPROFILE%\AppData\Local\node-gyp for Windows) first and then run yarn cache clean and then try again.

If you are on Windows or Linux 64 bit systems and would like to compile to 32 bit, you'll need to set the npm_config_arch environment variable to ia32 before running yarn. This will compile all native node modules for a 32 bit architecture. Similarly, when cross-compiling for ARM, set npm_config_arch to arm.

Note: For more information on how to install NPM modules globally on UNIX systems without resorting to sudo, refer to this guide.

If you have Visual Studio 2019 installed, you may face issues when using the default version of node-gyp. If you have Visual Studio 2019 installed, you may need to follow the solutions here.

  • Windows: If you have installed Visual Studio 2017 as your build tool, you need to open x64 Native Tools Command Prompt for VS 2017. Do not confuse it with VS2015 x64 Native Tools Command Prompt, if installed.
  • Linux: You may hit a ENOSPC error when running the build. To get around this follow instructions in the Common Questions.

If the build step fails, or if the built version fails to run (see next section), run git clean -xfd in your vscode folder, then re-run yarn.

Errors and Warnings

Errors and warnings will show in the console while developing VS Code. If you use VS Code to develop VS Code, errors and warnings are shown in the status bar at the bottom left of the editor. You can view the error list using View | Errors and Warnings or pressing Ctrl+P and then ! (CMD+P and ! on macOS).

👉 Tip! You don't need to stop and restart the development version of VS Code after each change. You can just execute Reload Window from the command palette. We like to assign the keyboard shortcut Ctrl+R (CMD+R on macOS) to this command.

Automated Testing

Run the unit tests directly from a terminal by running ./scripts/test.sh from the pearai-app folder (scripts\test on Windows).

We also have automated UI tests. The smoke test README has all the details.

Unit Testing

Run the tests directly from a terminal by running ./scripts/test.sh from the vscode folder (scripts\test on Windows). The test README has complete details on how to run and debug tests, as well as how to produce coverage reports.

Linting

We use eslint for linting our sources. You can run eslint across the sources by calling yarn eslint from a terminal or command prompt. You can also run yarn eslint as a VS Code task by pressing Ctrl+P (CMD+P on macOS) and entering task eslint.

To lint the source as you make changes you can install the eslint extension.

Work Branches

Even if you have push rights on the trypear/pearai-app repository, you should create a personal fork and create feature branches (yourname/branch-name, e.g. pan/open-chat-shortcut) there when you need them. This keeps the main repository clean and your personal workflow cruft out of sight.

Pull Requests

Before we can accept a pull request from you, you'll need to sign a [[Contributor License Agreement (CLA)|Contributor-License-Agreement]]. It is an automated process and you only need to do it once.

To enable us to quickly review and accept your pull requests, always create one pull request per issue and link the issue in the pull request. Never merge multiple requests in one unless they have the same root cause. Be sure to follow our [[Coding Guidelines|Coding-Guidelines]] and keep code changes as small as possible. Avoid pure formatting changes to code that has not been modified otherwise. Pull requests should contain tests whenever possible.

Creating Issues

Before you submit an issue, please do a search in open issues to see if the issue or feature request has already been filed. Use the provided issue template when creating a new issue. Fill in the template with as much detail as possible. The more detail you provide, the more likely that someone can help you. Alternatively, you can use Pear to create a ticket for the problem first. Simply describe the issue or feature request, and Pear will create a ticket for it. This can help you understand the problem better and guide you in manually solving it. You can also use Pear to create tickets. Simply describe the issue or feature request, and Pear will create a ticket for it.

You can also directly ping the maintainers or admins in the Discord.

Submitting Pull Requests

If you're working on an existing issue, respond to the issue and express interest in working on it. This helps other people know that the issue is active, and hopefully prevents duplicated efforts.

To submit a pull request, follow the following steps:

  1. Clone the repository.
  2. Create a new branch from main.
  3. Make your changes.
  4. Push your branch and submit a pull request to the main branch.
  5. Await review. Respond to any comments or requests made by reviewers.

Important Notes

  1. Please do not edit the structure of the repo. Pear is constantly changing, and we want to make sure that we can easily integrate your changes into our codebase.

Coding Standards

Please ensure your code adheres to the coding standards used throughout the project. This includes proper indentation, accurate comments, and clear, concise code.

Community

Please be respectful and considerate of others. We're all here to learn and grow, so constructive, respectful communication is encouraged.

Packaging

This section outlines how to package the app for a new release / distribution. This process is a bit manual currently.

Step 1: Package PearAI App

PearAI can be packaged for the following platforms: win32-ia32 | win32-x64 | darwin-x64 | darwin-arm64 | linux-ia32 | linux-x64 | linux-arm

These gulp tasks are available:

  • vscode-[platform]: Builds a packaged version for [platform].
  • vscode-[platform]-min: Builds a packaged and minified version for [platform].
  1. If you have not already, run ./scripts/pearai/setup-environment.[sh,ps1] (Note that .sh or .ps1 depends on your OS)
  2. If have already ran that upon your first install, run ./scripts/pearai/install-dependencies.[sh,ps1] (Note that .sh or .ps1 depends on your OS)
  3. Run yarn gulp vscode-[platform]. For example yarn gulp vscode-linux-x64

This will generate the new PearAI app and takes around 1 hour.

Step 2: Package PearAI Extension

pearai-submodule also needs to be packaged and integrated into the overall PearAI app.

To do this, follow these steps. Some are manual.

  1. cd into extensions/pearai-submodule
  2. Run ./scripts/install-dependencies.sh
  3. cd into extensions/vscode (Full path is now extensions/pearai-submodule/extensions/vscode/)
  4. Run npm run package
  5. This will create the .vsix extension within extensions/pearai-submodule/extensions/vscode/build
  6. Right-click the .vsix in VSCode or PearAI and select Install vsix as Extension. This will install the extension as a compatible dist for your system:
    • If you are using VSCode it will be:
      • Windows: %USERPROFILE%\.vscode\extensions
      • macOS: ~/.vscode/extensions
      • Linux: ~/.vscode/extensions
    • If you are using PearAI it will be:
      • Windows: %USERPROFILE%\.pearai\extensions
      • macOS: ~/.pearai/extensions
      • Linux: ~/.pearai/extensions

Step 3: Integrate the Extension

  1. Copy the contents of the generated extensions folder into the extensions/ folder of the packaged PearAI App. For example, on macOS, it is:
    • cp -r ~/.vscode/extensions/pearai.pearai-0.9.156 {path_to_PearAI.app}/Contents/Resources/app/extensions
  2. Take a quick look into the extensions/ folder of the packaged PearAI app for any other pearai folders. For example, there will be a pearai-submodule folder. Delete it. For example, on macOS, it is:
    • rm -rf {path_to_PearAI.app}/Contents/Resources/app/extensions/pearai-submodule
  3. Double-click your overall PearAI app, and the extension should be built-in.
  4. Distribute the application.

Step 4: Signing and Turn Into Installer

We changed the contents of the app. Admin must sign the app on certain OS's, like MacOS. Admin should follow these manuals

Known or Common Errors

Below describes a set of known or common errors that can occur when developing with PearAI and the steps that can resolve such issues.

Error: No main.js found

The following issue can occur after the build process:

``` [Error: ENOENT: no such file or directory, open '/pearai/out/vs/code/electron-main/main.js'] { errno: -2, code: 'ENOENT', syscall: 'open', path: '/code/pearai/out/vs/code/electron-main/main.js', phase: 'loading', moduleId: 'vs/code/electron-main/main', neededBy: [ '===anonymous1===' ] } ```

Steps to Resolve:

  1. Remove the build: rm -rf out
  2. Re-run the app: ./scripts/code.sh
  3. If this persists, please reach out via the communication channels listed in the Contact section.