onedeuxtriseigo.nullpo.dev
Pop-up dictionary browser extension for language learning. Successor to Yomichan. (PERSONAL FORK)
1# Issues and Features
2
3Issues reported on [GitHub](https://github.com/yomidevs/yomitan/issues) should include information about:
4
5- What the problem, question, or request is.
6- What browser is being used.
7- What version of Yomitan is being used.
8- If applicable, an export of the settings file.
9
10# Development
11
12Contributions are welcome from any developers who would like to help out.
13Below are a few guidelines to ensure contributions have a good level of quality and consistency:
14
15- Open GitHub issues to discuss large features before writing code.
16- Follow the [conventions and style](#style) of the existing code.
17- Test changes using the continuous integration tests included in the repository.
18- Write clean, modern ES6 code (`const`/`let`, `async`/`await`, arrow functions, etc.)
19- Large pull requests without a clear scope will not be merged.
20- Incomplete or non-standalone features will not be merged.
21
22## Setup
23
24Yomitan uses [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) tools for building and testing.
25After installing these, the development environment can be set up by running `npm ci` and subsequently `npm run build`.
26
27## Testing
28
29Unit tests, integration tests, and various other tests can be executed by running `npm test`.
30Other individual tests can be looked up in the [package.json](package.json) file, and the source for specific tests
31can be found in the [test](test) directory
32
33### Playwright
34
35Steps to run [playwright](https://playwright.dev/) tests locally:
36
371. Run `npx playwright install` to install the headless browsers
382. Copy the dictionary test data located in the `dictionaries` branch to a directory named `dictionaries` via `git clone --branch dictionaries git@github.com:yomidevs/yomitan.git dictionaries` ([source](https://github.com/yomidevs/yomitan/blob/086e043856ad54cf13cb65f9ba4c63afe8a22cc3/.github/workflows/playwright.yml#L52-L57)).
393. Now you can run `npx playwright test`. The first run might produce some benign errors complaining about `Error: A snapshot doesn't exist at ...writing actual.`, but subsequent runs should succeed.
40
41## Building
42
43By default, the development repository is configured for Chrome, and the [ext](ext) directory can be directly
44loaded as an unpacked extension by Chrome. This way, development does not require any additional build steps,
45and most changes will be automatically updated by the browser. Depending on what files were changed,
46the extension may sometimes need to be reloaded before the changes take effect.
47
48There are two scripts to build the extension to a packaged file for various build targets:
49
50- [build.bat](build.bat) on Windows
51- [build.sh](build.sh) on Linux
52
53Both of these files are convenience scripts which invoke <code>node [dev/bin/build.js](dev/bin/build.js)</code>.
54The build script can produce several different build files based on manifest configurations defined in
55[manifest-variants.json](dev/data/manifest-variants.json).
56Several command line arguments are available for these scripts:
57
58- `[target]` - Builds a specific target.
59- `--all` - Builds all targets specified in [manifest-variants.json](dev/data/manifest-variants.json).
60- `--default` - Restores the default manifest file.
61- `--manifest <target>` - Overwrites `ext/manifest.json` with the manifest variant for the specified build target.
62- `--dryRun` - Runs the full build process (excluding zip building), checking that the configuration is valid.
63- `--dryRunBuildZip` - If `--dryRun` is also specified, zip building will also be performed in memory; no files are created.
64- `--version <version>` - Sets the version number in the extension manifest. Defaults to 0.0.0.0 if not set.
65
66If no arguments are specified, the command is equivalent to `build.bat --all`.
67
68### Loading an unpacked build into Chromium browsers
69
70After building, you can load the compiled extension into Chromium browsers.
71
72- Navigate to the [extensions page](chrome://extensions/)
73- Turn on the toggle on the top right that says "Developer Mode"
74- Click "Load Unpacked" on the top left
75- Select the `ext` folder.
76
77Immediately you should see the "Welcome" page!
78
79Note: Yomitan may or may not update when you make and save new code changes locally. It depends on what file you've changed. Yomitan runs as collection of two programs. There is the background process called the "service worker" and there is the frontend called the "content_script". The frontend will reload on save, but to update the backend you need to click on the update icon next to the extension in `chrome://extensions/`. If you make changes to the manifest you will need to rerun `npm run build` to regenerate the manifest file.
80
81### Loading a build into Firefox browser
82
83After building, you can load the compiled extension into the Firefox browser.
84
85- Navigate to the Debugging page, type `about:debugging` into the url
86- Click on "This Firefox" on the left
87- Click on "Load Temporary Add-on" on the right
88- Navigate to the `yomitan-firefox-dev.zip` in your builds folder
89
90Immediately you should see the "Welcome" page!
91
92Note: The "Load Temporary Add-on" option is temporary and the build will need to be loaded again after browser restarts. Sometimes testing extension features between browser restarts will be necessary so here are the steps to bypass this restriction.
93
94- Download Firefox Developer or Nightly
95- Navigate to the Config page, type `about:config` into the url
96- Look up `xpinstall.signatures.required` setting on the search bar at the top
97- Toggle the value to "false"
98- Navigate to the "Extensions" page using "Manage extensions"
99- Either use drag and drop or "Install Add-on from File" to load the dev build
100
101### Loading an unpacked build into Microsoft Edge browser
102
103After building, you can load the compiled extension into the Edge browser.
104
105- Unpack the `yomitan-edge.zip`
106- Navigate to the extension page using the "..." on the top right and clicking on "Manage extensions"
107- Turn on the toggle on the left that says "Developer Mode"
108- Click "Load unpacked" on the top right
109- Select the unpacked `yomitan-edge` folder
110
111Immediately you should see the "Welcome" page!
112
113### Build Tools
114
115The build process can use the [7-zip](https://www.7-zip.org/) archiving tool to create the packed zip builds
116if the 7-zip executable (either `7z` or `7za`) is found in the `PATH` environment variable.
117Otherwise, the [JSZip](https://stuk.github.io/jszip/) API is used to generate the files.
1187-zip typically provides better compression than JSZip, but the files are otherwise equivalent.
119
120## Manifest
121
122Manifest variants for different build targets are specified in [manifest-variants.json](dev/data/manifest-variants.json).
123This file is used to generate the `ext/manifest.json` file included in the extension.
124The generated `ext/manfiest.json` should not be committed.
125
126## Style
127
128Linting rules are defined for a few types of files, and validation is performed as part of the standard tests
129run by `npm test` and the continuous integration process.
130
131- [eslint.config.js](eslint.config.js) rules are used for JavaScript files.
132- [.stylelintrc.json](.stylelintrc.json) rules are used for CSS files.
133- [.htmlvalidate.json](.htmlvalidate.json) rules are used for HTML files.
134
135In addition, the [Markdown All in One VSCode extension](https://github.com/yzhang-gh/vscode-markdown) is used for formatting markdown files and automatically updating the table of contents.
136
137## Commit Signing
138
139We highly recommend signing your commits in git.
140
141While it's possible to use GPG for this, we recommend using SSH keys for your signing. Furthermore, if you have appropriate hardware support (which most modern machines do), we recommend storing the key in a hardware TPM so it's impossible for malware to steal it off your machine.
142
143### Understanding why
144
145GitHub already requires a key when you connect to it for basic git operations (pull, push, etc.). They call this the "authentication key" and it is an SSH key. You presumably already have one of these if you have ever used GitHub for anything before.
146
147The commit signing key is different, and is used for signing the contents of a commit. This is important because it gives us much more useful git history where we actually have guarentees about who wrote what parts of the code. With no commit signing, it is easy with someone with push access to include commits with fake author names etc., which can be quite troubling when trying to figure out what has happened during a security incident. (See [this article](https://withblue.ink/2020/05/17/how-and-why-to-sign-git-commits.html) for more.)
148
149### Creating the SSH key for signing
150
151- On Mac, you can use [secretive](https://github.com/maxgoedjen/secretive) to have Secure Enclave-backed SSH operations.
152- On Linux, you can use [ssh-tpm-agent](https://github.com/Foxboron/ssh-tpm-agent) to use your hardware TPM for SSH operations.
153- On any OS, you can use a [YubiKey for SSH operations](https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html). A YubiKey is arguably slightly more secure than a normal TPM, especially if you get a YubiKey bio, but in our threat model we consider them to be equivalent so there is no need to buy one if you already have a TPM.
154- As a last resort if you're on old hardware and also don't have money to buy a YubiKey, you can create the SSH key on disk as opposed to in a TPM, but it's much more exposed to malware and supply chain attacks (e.g., a malcious npm package that steals SSH keys etc).
155
156When generating the signing key, we recommend requiring user verification (i.e., entering a PIN or presenting a biometric). However for the "authentication key" (the normal SSH key you use to do non-signed operations with GitHub (like pulls)), we do not consider it as important to have user verification as many of those operations are not very sensitive, and it can be annoying to present your verification factor when just doing a pull. Of course it doesn't hurt to have extra user verification security-wise as it's also used for pushes, but the malicious things that could be pushed would be limited since at most the attacker could remove some signed commits, but not create any.
157
158### Exposing your SSH key to git for commit signing
159
160Once you have set up your SSH key (either using the above hardware-backed methods for optimal security, or just a normal on-disk key if you don't have a TPM available in your hardware), you can expose it to git for signing operations as follows:
161
162```
163git config --global gpg.format ssh
164git config --global user.signingkey /path/to/key
165git config --global commit.gpgsign true
166```
167
168(Confusingly the option names have 'gpg' in them, but rest assured GPG is not involved once you switch the format to SSH with the first command.)
169
170### Registering your SSH key with GitHub
171
172Go to [https://github.com/settings/keys](https://github.com/settings/keys) and click "Add new SSH key". On the following page, make sure to change "Key type" to "Signing key". Then paste the public key into the textbox.
173
174With this, you are done and your commits should be signed (which you can see on the GitHub interface with the "Verified" green mark next to your commits).