How To Contribute
Generally speaking, you have many ways to help develop OpenSumi
code, for example, find a bug, write it down and submit a PR (Pull Requests), or simply give a piece of advice on a feature.
For issue marked with PR Welcome
, it is best to submit your first PR when you have any questions in the process. You can always consult any project member in the comment area by using "@" any project member.
Prepare Development Environment
The system tool installation method here refers to How-to-Contribute document of VS Code for translation, and you can directly view the document.
Before developing the code, you need to install some necessary development tools, clone our project code opensumi/core, and install dependencies through yarn
.
You may need the following development tools:
- Git
- Node.JS, version number
>= 16.x
,<= 18.x
- Python (pre-dependency of node-gyp library; view node-gyp readme and find a suitable version currently supported)
- Note: Windows users install Python automatically when installing the npm module of
windows-build-tools
. It can be quickly installed in this way as follows:
- Note: Windows users install Python automatically when installing the npm module of
- A C/C++ compilation tool suitable for your system:
- macOS
- To install Xcode and its command line tools will automatically install
gcc
, the installation process relies on themake
tool chain- Run
xcode-select --install
to install command line tools
- Run
- To install Xcode and its command line tools will automatically install
- Windows 10/11
- Install Windows Build Tools:
- If you install it by the Node installer provided by Node.JS and make sure you install the native module tools, the environment will be able to be used normally.
- If you manage scripts by Node version, for example, nvm or nvs
- Install the Python version corresponding to the current version Microsoft Store Package
- Install
Visual C++ Build Environment
: Visit and install Visual Studio Build Tools or Visual Studio Community Edition. The minimal installation mode is to installDesktop Development with C++
only - Open the command line and execute
npm config set msvs_version 2019
- Note: Make sure that your local PATH only contains ASCII characters, otherwise it may cause node-gyp usage problems (nodejs/node-gyp/ issues#297), and currently it does not support the project construction and debugging in earlier Windows version.
- Install Windows Build Tools:
- macOS
Build and Run
If you want to learn how to run OpenSumi or debug an issue, you need to get the code locally, build it and run it.
Obtain the Code
In the first step, you need to fork a copy of the OpenSumi
repository, and then clone it locally:
git clone https://github.com/<<<your-github-account>>>/core.git
Usually you need to synchronize the latest branch code in advance before modifying or submitting the code.
cd core
git checkout main
git pull https://github.com/opensumi/core.git main
After handling the code conflicts, you can submit the code to your repository, and go to opensumi/core to submit your PR at any time.
Note: The default opensumi/core
also contains a lot of GitHub Actions. If you don't want to execute these Actions, you can go to https://github.com/<<Your Username>>/core/settings/actions
to close the corresponding Actions.
Build
cd core
yarn
yarn run init
Run
After the initialization is complete, you can run the Web version directly by using the following command, and enable Hot Reload
at the same time. All modifications except the extension process can be seen in the Web in real time.
yarn start
By default, the framework will display the tools/workspace
directory under the project as the workspace directory. You can also open OpenSumi by specifying the path with MY_WORKSPACE=
, as shown below:
MY_WORKSPACE={workspace_path} npm start
Debug
There are multiple processes when OpenSumi is running. You need to determine the specific process you want to debug before you can debug them accordingly.
Browser process
As for the Browser process
, you can debug directly through Chrome Developer Tools
(recommended), or install [Debugger for Chrome](https: //marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) to debug the breakpoint of the Browser process
, as the picture shows:
Node process
As for the Node process
, after you run the framework through npm start
, you can make a breakpoint debugging of the Node process
by using VSCode
or Attach to BackEnd
in the IDE debug panel based on OpenSumi.
In addition, you can also use the Launch Backend
and Launch Frontend
in the debug panel to start the Node process
and Browser process
respectively for debugging.
Extension Process
As for the extension process
, you can use VSCode
or the Attach to Extension Host
method in the debugging panel built on OpenSumi to debug the extension process
. When it doesn't work sometimes, you can directly open chrome://inspect
panel to debug the code(easy to use). You can start to debug it after the framework is running by filling in localhost:9889
in the discovery port, as shown in the following figure:
Unit Test
We use Jest
for unit testing, combined with the mock capability implemented in @opensumi/di
to simulate and test the execution environment.
You can test the code of a module (the following code test module is debug, that is, the debug directory in the packages directory) by using the following command.
yarn run test:module -- --module=debug
You can also debug breakpoints on test files currently activated by the editor, using the Jest Current File
command in the debug panel.
Code Specification
When running yarn run lint
, you can directly retrieve the overall code specification. Meanwhile when the code is committed, corresponding code formatting checks will be triggered.
PR Rules
Each commit should be as small as possible, and you need to fill in your commit information in accordance with ng4's submission specifications.
For example, when you fix the variable acquisition problem of the debug module, the submission information can be as follows:
fix: fix variable acquisition under the debug panel
For PR content, just follow the PR and fill in the template.
Extension Process Debugging
If you want to debug the extension process under the OpenSumi framework, you can link your local extension process to the {root path}/tools/extensions
directory in the form of soft link, for example:
ln -s {local_path}/{extension_name} {root path}/tools/extensions/{extension_name}
You can quickly preview the effect by refreshing the page.
Spelling
For common spelling issues, We recommend that you install Code Spell Checker plug-in under VSCode
or an IDE built on OpenSumi, to avoid English spelling mistakes.
Feedback
We appreciate receiving suggestions and feature requirements for the OpenSumi framework. Welcome to submit and elaborate on Issues.