Skip to content

Commit 1e47cf7

Browse files
sheepzhsheepzh
authored
Create CONTRIBUTING.md
1 parent a05ba5f commit 1e47cf7

File tree

1 file changed

+183
-0
lines changed

1 file changed

+183
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Contributing Guide
2+
3+
## 1. Prerequisites
4+
5+
The technology stack used is:
6+
7+
- [webpack](https://github.com/webpack/webpack) + [TypeScript](https://github.com/microsoft/TypeScript)
8+
- [Vue3 (Composition API + JSX)](<https://vuejs.org/api/#:~:text=defineCustomElement()-,Composition%20API,-setup()>)
9+
- [sass](https://github.com/sass/sass)
10+
- [Element Plus](https://element-plus.gitee.io/)
11+
- [Echarts](https://github.com/apache/echarts)
12+
13+
And [Chrome Extension Development Documentation](https://developer.chrome.com/docs/webstore/). Currently, the manifest version used by Chrome and Edge is v3, and Firefox uses v2. Please pay attention to compatibility.
14+
15+
Some free open source tools are also integrated:
16+
17+
- Testing tool [jest](https://jestjs.io/docs/getting-started)
18+
- End-to-end integration testing [puppeteer](https://developer.chrome.com/docs/extensions/how-to/test/puppeteer)
19+
- I18N tool [Crowdin](https://crowdin.com/project/timer-chrome-edge-firefox)
20+
21+
## 2. Steps
22+
23+
1. Fork your repository
24+
2. Install dependencies
25+
26+
```shell
27+
npm install
28+
```
29+
30+
3. Create your own branch
31+
4. Code & run
32+
33+
First execute the command
34+
35+
```shell
36+
npm run dev
37+
# or if you want to run in Firefox
38+
npm run dev:firefox
39+
```
40+
41+
Two folders will be output in the project root directory, `dist_dev` and `dist_dev_firefox`
42+
43+
Then import different targets according to the test browser:
44+
45+
- Import `dist_dev` into Chrome and Edge
46+
- Import the `manifest.json` file in `dist_dev_firefox` for Firefox
47+
48+
5. Run unit tests
49+
50+
```shell
51+
npm run test
52+
```
53+
54+
6. Run end-to-end tests
55+
56+
First, you need to compile twice: integration compilation and production compilation
57+
58+
```shell
59+
npm run dev:e2e
60+
npm run build
61+
```
62+
63+
Then execute the test
64+
65+
```shell
66+
npm run test-e2e
67+
```
68+
69+
If you need to start puppeteer in headless mode, you can set the following environment variables
70+
71+
```bash
72+
export USE_HEADLESS_PUPPETEER=true
73+
```
74+
75+
7. Submit a PR
76+
77+
Please PR to the milestone branch of the main repository, which is usually the next minor version number (x.x.0). If it is not there, please contact the author to create it
78+
79+
## 3. Application architecture design
80+
81+
> todo
82+
83+
## 4. Directory Structure
84+
85+
```plain
86+
project
87+
│
88+
└───doc # Documents
89+
│
90+
└───public # Assets
91+
|
92+
└───src
93+
| | manifest.ts # manifest.json for Chrome and Edge
94+
| | manifest-firefox.ts # manifest.json for Firefox
95+
| |
96+
| └───api # API
97+
| |
98+
| └───pages # UI
99+
| | |
100+
| | └───app # Background page
101+
| | |
102+
| | └───popup # Popup page
103+
| | | |
104+
| | | └───skeleton.ts # Skeleton of the popup page
105+
| | | |
106+
| | | └───index.ts # Popup page entrance
107+
| | |
108+
| | └───side # Side page
109+
| | |
110+
| | └───[Other dirs] # Shared code
111+
| |
112+
| └───background # Backend service, responsible for coordinating data interaction, Service Worker
113+
| |
114+
| └───content-script # Script injected into user pages
115+
| |
116+
| └───service # Service Layer
117+
| |
118+
| └───database # Data Access Layer
119+
| |
120+
| └───i18n # Translations
121+
| |
122+
| └───util # Utils
123+
| |
124+
| └───common # Shared
125+
|
126+
└───test # Unit tests
127+
| └───__mock__
128+
| |
129+
| └───storage.ts # mock chrome.storage
130+
|
131+
└───test-e2e # End-to-end tests
132+
|
133+
└───types # Declarations
134+
|
135+
└───webpack # webpack config
136+
137+
```
138+
139+
## 5. Code format
140+
141+
Please use the code formatting tools that come with VSCode. Please <u>**disable Prettier Eslint**</u> and other formatting tools
142+
143+
- Use single quotes whenever possible
144+
- Keep the code as concise as possible while being grammatically correct.
145+
- No semicolon at the end of the line
146+
- Please use LF (\n). In Windows, you need to execute the following command to turn off the warning:
147+
148+
```
149+
git config core.autocrlf false
150+
```
151+
152+
## 6. How to use i18n
153+
154+
Except for certain professional terms, the text of the user interface can be in English. For the rest, please use i18n to inject text. See the code directory `src/i18n`
155+
156+
### How to add entries
157+
158+
1. Add new fields in the definition file `xxx.ts`
159+
2. Then <u>add the corresponding text of this field in English (en) and Simplified Chinese (zh_CN)</u> in the corresponding resource file `xxx-resource.json`
160+
3. Call `t(msg=>msg...)` in the code to get the text content
161+
162+
### How to integrate with Crowdin
163+
164+
Crowdin is a collaborative translation platform that allows native speakers to help translate multilingual content. The project's integration with Crowdin is divided into two steps
165+
166+
1. Upload English text and other language text in code
167+
168+
```
169+
# Upload original English text
170+
ts-node ./script/crowdin/sync-source.ts
171+
# Upload texts in other languages ​​in local code (excluding Simplified Chinese)
172+
ts-node ./script/crowdin/sync-translation.ts
173+
```
174+
175+
Because the above two scripts rely on the Crowdin access secret in the environment variable, I integrated them into Github's [Action](https://github.com/sheepzh/timer/actions/workflows/crowdin-sync.yml)
176+
177+
2. Export translations from Crowdin
178+
179+
```
180+
ts-node ./script/crowdin/export-translation.ts
181+
```
182+
183+
You can also directly execute [Action](https://github.com/sheepzh/timer/actions/workflows/crowdin-export.yml).

0 commit comments

Comments
 (0)