Skip to content

Commit

Permalink
[docs] Add starter documents (Samsung#1629)
Browse files Browse the repository at this point in the history
* [docs] Add starter documents

This commit adds an introductory document for this project.

ONE-vscode-DCO-1.0-Signed-off-by: Dayoung Lee <[email protected]>
  • Loading branch information
dayo09 authored Sep 14, 2023
1 parent f6d2b6b commit 7c3bb67
Show file tree
Hide file tree
Showing 3 changed files with 107 additions and 0 deletions.
58 changes: 58 additions & 0 deletions docs/developers/HowToContribute.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
### Introduction

This is an introductory page explaining the contribution process for beginners.

### How to contribute?

#### Sign-off

[ONE-vscode-Developer's Certificate of Origin](https://github.com/Samsung/ONE-vscode/wiki/ONE-vscode-Developer\'s-Certificate-of-Origin)

All the ONE-vscode contributors abide by this Certificate of Origin.
This signing off means that you certifies yourself about this.

At the end of your commit, please add this line.

> ONE-vscode-DCO-1.0-Signed-off-by: Random O Developer <[email protected]>
NOTE that you need to embrace your email with '<' and '>'.

Without this Sign-off, your commit will fail the CI.

For your convenience, add a git hook as explained in the [ONE-vscode-Developer's Certificate of Origin](https://github.com/Samsung/ONE-vscode/wiki/ONE-vscode-Developer\'s-Certificate-of-Origin) page.

#### Format

This project uses a formatter to keep consistency in its style.
We use `prettier`.
Your Pull Request will fail the CI if you don't follow this formatter's style.
It is included in our npm dependency, so additional installation of formatter is not needed.

```bash
cd ONE-vscode
bash infra/format
```

#### Run Unit Test Locally

If any of existing unit tests fails, CI rejects your pull request.
To prevent this, you can run unit tests on your computer before you make your pr.

```bash
npm run test
```

This command will install all the required tools to run your test and pop up a vscode development host.

If you are connecting to your remote development environment, vscode development host cannot pop up, not proceeding the test.
However, there is a way. This will run the test without display.

```bash
npm run test-no-screen
```

#### Add Unit Test (Recommended)

Mind that your PR must pass the mocha test.
It's always recommended that you write your own unit test with your PR.
Please find `src/Tests` directory. It has the same directory tree with source. All the corresponding files includes corresponding unit tests.
49 changes: 49 additions & 0 deletions docs/developers/HowToStart.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
### Introduction

This pages is an introductory page for the ONE-vscode developers who want to try for the first time.

### Simple explanation on development environment
VSCode is a NodeJS project as it is built with the `electron` framework.
`electron` is a popular framework built on NodeJS. The familiar services as 'notion' or 'slack' are built on it, too.

You need to first install Node Package Manager(`npm`). Please find `package.json` file in the root directory of this project. It has all the dependencies as long as the other major configuration of this project. In 'devDependencies' section, you can see that it includes @types/node and @types/vscode.

If you hit F12 on `import * as vscode from "vscode"` line, you can enter index.d.ts which has definitions of all vscode APIs you need. The documentation in comment is helpful enough sometimes, but to find more detailed description, go to [VSCode's official API page](https://code.visualstudio.com/api).

### How to build the extension and debug?

1. You must have `npm`(node package manager) installed.
`npm` is a package manager like pip or apt.
Likewise python virtual env, it manages packages directory by directory.

```bash
sudo apt install npm
```

2. Clone the repository

```bash
git clone https://github.com/Samsung/ONE-vscode.git
```

3. Run `npm install`
npm will prepare dependencies in `node_modules`.

```bash
cd ONE-vscode
npm install
```

4. For debug, open the vscode window and simply Press F5.
Another vscode window will be popped up and its name is 'Extension Development Host'.
<img src="run-dev-host.gif"/>
Click 'ONE' icon on the left side.

You can also try the beginner's example from ["Your First Extension" page of vscode official](code.visualstudio.com/api/get-started/your-first-extension).


### Helpful pages
- [VSCode's official API page](https://code.visualstudio.com/api)
- Most vscode API is documented very well.
- [VSCode extension sample repository](https://github.com/microsoft/vscode-extension-samples.git)
- You can try the sample basic extensions.
Binary file added docs/developers/run-dev-host.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 7c3bb67

Please sign in to comment.